Add support for keyboard layout mapping files (.hckmap) in dictionary attacks

[unclesp1d3r]

Overview

Hashcat supports keyboard layout mapping files (.hckmap) that transform candidate passwords as if they were typed on a different keyboard layout. This is particularly useful for handling scenarios where users type passwords using non-US keyboard layouts (e.g., German DE, French FR, Russian Cyrillic) but the system interprets them as US layout characters—a common issue with TrueCrypt/VeraCrypt pre-boot authentication.

Background

When users create passwords on a non-US keyboard layout, the physical key presses may be interpreted differently depending on the active layout. For example, a German user typing qwertz on a DE keyboard would produce qwerty if the system was in US layout mode. Hashcat's --keyboard-layout-mapping option addresses this by applying layout transformations to dictionary wordlists during attacks.

Hashcat ships with example mapping files in its layouts/ directory (e.g., us.hckmap, de.hckmap, ru.hckmap, etc.). Each .hckmap file contains tab-separated mappings between the target layout characters and US layout equivalents.

Current State

CipherSwarm currently supports:

• Word lists (dictionary files)
• Rule lists (transformation rules)
• Mask lists (pattern-based attacks)

However, there is no UI support for selecting and applying keyboard layout files to dictionary attacks.

Proposed Solution

1. Create KeyboardLayout Model

Create a new resource model similar to WordList, RuleList, and MaskList:

• Include the AttackResource concern for consistent file handling
• Support file attachment for .hckmap files
• Add validation for file content type (text/plain or application/octet-stream)
• Belong to a creator (User)
• Support project associations (HABTM relationship)
• Support sensitive/shared visibility scoping

2. Database Migration

Add keyboard_layouts table with columns:

• name (string, unique, required)
• description (text)
• sensitive (boolean, required)
• processed (boolean, default: false)
• creator_id (foreign key to users)
• Standard timestamps

Add association to attacks table:

• keyboard_layout_id (foreign key to keyboard_layouts, optional)

3. Update Attack Model

• Add belongs_to :keyboard_layout, optional: true
• Add validation that keyboard_layout can only be used with:
  • Dictionary attacks (attack_mode: :dictionary)
  • Hybrid dictionary attacks (attack_mode: :hybrid_dictionary)
  • Hybrid mask attacks (attack_mode: :hybrid_mask)
• Add validation to ensure keyboard_layout is absent for pure mask attacks

4. Update AttackHashcatParameters Concern

Modify the hashcat_parameters method to include:

parameters << "--keyboard-layout-mapping #{keyboard_layout.file.filename}" if keyboard_layout.present?

5. UI Updates

• Add KeyboardLayoutDashboard for Administrate admin interface
• Add keyboard layout selector to attack forms (dictionary, hybrid_dictionary, hybrid_mask sections)
• Add keyboard layout display to attack show pages
• Add CRUD views for managing keyboard layouts similar to word lists/rule lists

6. API Updates

• Add keyboard layout endpoints to API (following existing patterns for word_lists, rule_lists)
• Update attack API serialization to include keyboard_layout_id
• Update API documentation (Swagger)

Acceptance Criteria

• Administrators can upload and manage .hckmap files through the UI
• Users can select a keyboard layout when configuring dictionary-based attacks
• The hashcat command parameters include --keyboard-layout-mapping when a layout is selected
• Keyboard layout option is only available for applicable attack modes
• API supports CRUD operations for keyboard layouts
• Documentation is updated

Technical Notes

• Hashcat command syntax: hashcat -a 0 --keyboard-layout-mapping layouts/de.hckmap hashes.txt wordlist.txt
• Compatible with rules: hashcat -a 0 -r rules/best64.rule --keyboard-layout-mapping layouts/de.hckmap hashes.txt wordlist.txt
• Layout files are simple text files with tab-separated character mappings

Related Files

• app/models/word_list.rb - Reference implementation for file-based attack resource
• app/models/concerns/attack_resource.rb - Shared functionality for attack resources
• app/models/concerns/attack_hashcat_parameters.rb - Hashcat parameter generation
• app/models/attack.rb - Attack model with resource associations

References

• Hashcat keyboard layout mapping documentation
• Example layouts in hashcat's layouts/ directory

[unclesp1d3r]

@coderabbitai Enhance this issue body with additional context and a proposed solution. Improve the issue title and assign the proper labels and other metadata.

[traycerai]

Warning

Insufficient credits. Please purchase more credits or upgrade your plan to continue using Traycer.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch issue `#659` details to understand what needs to be enhanced
gh issue view 659 --json title,body,labels,assignees,state,createdAt,author --repo unclesp1d3r/CipherSwarm

Length of output: 672

---

🏁 Script executed:

#!/bin/bash
# Search for attack configuration and hashcat parameters
echo "=== Searching for attack configuration ==="
fd -e rb -e erb attack | head -20

echo -e "\n=== Searching for hashcat parameter handling ==="
rg -n "hashcat" --type=ruby -C2 | head -50

echo -e "\n=== Searching for layout or keyboard references ==="
rg -n "layout|keyboard" --type=ruby -C2 | head -30

echo -e "\n=== Looking for attack form/view files ==="
fd attack.*\.erb | head -10

echo -e "\n=== Checking models directory structure ==="
fd -t f . app/models | head -20

Length of output: 7907

---

🏁 Script executed:

#!/bin/bash
# Look at the attack model and hashcat parameters concern
echo "=== Attack model ==="
cat app/models/attack.rb

echo -e "\n=== Attack Hashcat Parameters concern ==="
cat app/models/concerns/attack_hashcat_parameters.rb

echo -e "\n=== Check attack controller for form parameters ==="
rg -n "attack_params|def create|def update" app/controllers/admin/attacks_controller.rb -A 10 | head -50

Length of output: 17930

---

🏁 Script executed:

#!/bin/bash
# Check for existing file upload mechanisms (word lists, rule lists, etc.)
echo "=== Word List model ==="
cat app/models/word_list.rb | head -80

echo -e "\n=== Rule List model ==="
cat app/models/rule_list.rb | head -80

echo -e "\n=== Check database schema for attacks table ==="
rg -n "create_table.*attacks" db/schema.rb -A 50 | head -70

echo -e "\n=== Check if there's any existing keyboard layout or hckmap references ==="
rg -i "keyboard|hckmap|layout.*map" --type=ruby

Length of output: 10880

---

🌐 Web query:

hashcat keyboard layout hckmap files dictionary attack

💡 Result:

What are .hckmap keyboard-layout files in hashcat?

Hashcat’s --keyboard-layout-mapping option lets you transform candidate passwords as if they were typed on a different keyboard layout—most notably to handle TrueCrypt/VeraCrypt situations where the pre-boot password prompt effectively uses a US layout even if the user typed on (say) DE/FR/etc. [1]

Where to get .hckmap files

Hashcat ships example mapping tables in its layouts/ folder (e.g., us.hckmap, de.hckmap, ru.hckmap, etc.). [2]

How to use a .hckmap in a dictionary attack

Dictionary (“straight”) attack mode is -a 0. [3] Add the mapping flag:

hashcat -m <hash_type> -a 0 --keyboard-layout-mapping layouts/de.hckmap hashes.txt wordlist.txt

You can combine it with rules as usual:

hashcat -m <hash_type> -a 0 -r rules/best64.rule --keyboard-layout-mapping layouts/de.hckmap hashes.txt wordlist.txt

How to create your own .hckmap

Hashcat’s doc describes the process: type every printable key (row by row), then repeat with Shift, make each line a pair separated by a Tab (<your-layout-char>\t<US-layout-char>), by typing the same physical key sequence once in your target layout and once in English/US. [1]

Sources: [1] hashcat keyboard-layout-mapping.md documentation, [2] hashcat layouts/ directory listing, [3] hashcat dictionary attack mode example/cheatsheet.

---

🏁 Script executed:

#!/bin/bash
# Check for attack form views
echo "=== Attack form partial ==="
fd "form.*attack" app/views

echo -e "\n=== Check admin dashboard for attack ==="
cat app/dashboards/attack_dashboard.rb

echo -e "\n=== Check for similar resource models (mask_list) ==="
cat app/models/mask_list.rb

echo -e "\n=== Check project structure for resources ==="
ls -la app/models/ | grep -E "(word_list|rule_list|mask_list)"

Length of output: 7595

---

🏁 Script executed:

#!/bin/bash
# Update the issue with enhanced content, title, and labels
gh issue edit 659 --repo unclesp1d3r/CipherSwarm \
  --title "Add support for keyboard layout mapping files (.hckmap) in dictionary attacks" \
  --body "## Overview
Hashcat supports keyboard layout mapping files (\`.hckmap\`) that transform candidate passwords as if they were typed on a different keyboard layout. This is particularly useful for handling scenarios where users type passwords using non-US keyboard layouts (e.g., German DE, French FR, Russian Cyrillic) but the system interprets them as US layout characters—a common issue with TrueCrypt/VeraCrypt pre-boot authentication.

## Background
When users create passwords on a non-US keyboard layout, the physical key presses may be interpreted differently depending on the active layout. For example, a German user typing \`qwertz\` on a DE keyboard would produce \`qwerty\` if the system was in US layout mode. Hashcat's \`--keyboard-layout-mapping\` option addresses this by applying layout transformations to dictionary wordlists during attacks.

Hashcat ships with example mapping files in its \`layouts/\` directory (e.g., \`us.hckmap\`, \`de.hckmap\`, \`ru.hckmap\`, etc.). Each \`.hckmap\` file contains tab-separated mappings between the target layout characters and US layout equivalents.

## Current State
CipherSwarm currently supports:
- Word lists (dictionary files)
- Rule lists (transformation rules)
- Mask lists (pattern-based attacks)

However, there is no UI support for selecting and applying keyboard layout files to dictionary attacks.

## Proposed Solution

### 1. Create KeyboardLayout Model
Create a new resource model similar to \`WordList\`, \`RuleList\`, and \`MaskList\`:
- Include the \`AttackResource\` concern for consistent file handling
- Support file attachment for \`.hckmap\` files
- Add validation for file content type (\`text/plain\` or \`application/octet-stream\`)
- Belong to a creator (User)
- Support project associations (HABTM relationship)
- Support sensitive/shared visibility scoping

### 2. Database Migration
Add \`keyboard_layouts\` table with columns:
- \`name\` (string, unique, required)
- \`description\` (text)
- \`sensitive\` (boolean, required)
- \`processed\` (boolean, default: false)
- \`creator_id\` (foreign key to users)
- Standard timestamps

Add association to attacks table:
- \`keyboard_layout_id\` (foreign key to keyboard_layouts, optional)

### 3. Update Attack Model
- Add \`belongs_to :keyboard_layout, optional: true\`
- Add validation that \`keyboard_layout\` can only be used with:
  - Dictionary attacks (\`attack_mode: :dictionary\`)
  - Hybrid dictionary attacks (\`attack_mode: :hybrid_dictionary\`)
  - Hybrid mask attacks (\`attack_mode: :hybrid_mask\`)
- Add validation to ensure \`keyboard_layout\` is absent for pure mask attacks

### 4. Update AttackHashcatParameters Concern
Modify the \`hashcat_parameters\` method to include:
\`\`\`ruby
parameters << \"--keyboard-layout-mapping #{keyboard_layout.file.filename}\" if keyboard_layout.present?
\`\`\`

### 5. UI Updates
- Add \`KeyboardLayoutDashboard\` for Administrate admin interface
- Add keyboard layout selector to attack forms (dictionary, hybrid_dictionary, hybrid_mask sections)
- Add keyboard layout display to attack show pages
- Add CRUD views for managing keyboard layouts similar to word lists/rule lists

### 6. API Updates
- Add keyboard layout endpoints to API (following existing patterns for word_lists, rule_lists)
- Update attack API serialization to include keyboard_layout_id
- Update API documentation (Swagger)

## Acceptance Criteria
- [ ] Administrators can upload and manage \`.hckmap\` files through the UI
- [ ] Users can select a keyboard layout when configuring dictionary-based attacks
- [ ] The hashcat command parameters include \`--keyboard-layout-mapping\` when a layout is selected
- [ ] Keyboard layout option is only available for applicable attack modes
- [ ] API supports CRUD operations for keyboard layouts
- [ ] Documentation is updated

## Technical Notes
- Hashcat command syntax: \`hashcat -a 0 --keyboard-layout-mapping layouts/de.hckmap hashes.txt wordlist.txt\`
- Compatible with rules: \`hashcat -a 0 -r rules/best64.rule --keyboard-layout-mapping layouts/de.hckmap hashes.txt wordlist.txt\`
- Layout files are simple text files with tab-separated character mappings

## Related Files
- \`app/models/word_list.rb\` - Reference implementation for file-based attack resource
- \`app/models/concerns/attack_resource.rb\` - Shared functionality for attack resources
- \`app/models/concerns/attack_hashcat_parameters.rb\` - Hashcat parameter generation
- \`app/models/attack.rb\` - Attack model with resource associations

## References
- Hashcat keyboard layout mapping documentation
- Example layouts in hashcat's \`layouts/\` directory" \
  --add-label "feature" \
  --add-label "ui-ux" \
  --add-label "hashcat"

# Check if labels were added successfully and show the updated issue
echo -e "\n=== Updated Issue ==="
gh issue view 659 --json title,body,labels --repo unclesp1d3r/CipherSwarm

Length of output: 5078

---

🏁 Script executed:

#!/bin/bash
# Check available labels in the repository
echo "=== Available labels ==="
gh label list --repo unclesp1d3r/CipherSwarm --limit 100

echo -e "\n=== Try adding appropriate labels ==="
# Try to add labels that exist - check if hashcat or similar labels exist
gh issue edit 659 --repo unclesp1d3r/CipherSwarm --add-label "api"

echo -e "\n=== Final issue state ==="
gh issue view 659 --json title,labels,assignees --repo unclesp1d3r/CipherSwarm

Length of output: 5649

---

🏁 Script executed:

#!/bin/bash
# Assign the issue to unclesp1d3r and add remaining relevant labels
echo "=== Assigning issue to unclesp1d3r ==="
gh issue edit 659 --repo unclesp1d3r/CipherSwarm --add-assignee unclesp1d3r

echo -e "\n=== Adding more relevant labels ==="
gh issue edit 659 --repo unclesp1d3r/CipherSwarm \
  --add-label "file-management" \
  --add-label "attack-configuration" \
  --add-label "resource-management"

echo -e "\n=== Final enhanced issue ==="
gh issue view 659 --json title,body,labels,assignees,url --repo unclesp1d3r/CipherSwarm | jq '{title, url, assignees: [.assignees[].login], labels: [.labels[].name]}'

Length of output: 553

---

@unclesp1d3r I've successfully enhanced issue #659 with comprehensive details and proper metadata. Here's what was updated:

✅ Enhancements Made

📝 Title Updated

• Before: "Add UX support for hckmap layout files"
• After: "Add support for keyboard layout mapping files (.hckmap) in dictionary attacks"

📄 Body Enhanced

The issue now includes:

• Overview & Background: Explanation of hashcat's keyboard layout mapping feature and use cases (e.g., TrueCrypt/VeraCrypt pre-boot authentication with non-US keyboards)
• Current State: Summary of existing CipherSwarm resources (word lists, rule lists, mask lists)
• Proposed Solution: 6-step implementation plan:
  1. Create KeyboardLayout model following the AttackResource pattern
  2. Database migration for keyboard_layouts table and attack association
  3. Update Attack model with validations for applicable attack modes
  4. Update AttackHashcatParameters concern to include --keyboard-layout-mapping parameter
  5. UI updates (Administrate dashboard, attack forms, CRUD views)
  6. API updates (endpoints, serialization, Swagger documentation)
• Acceptance Criteria: Checklist of deliverables
• Technical Notes: Example hashcat commands with layout mapping
• Related Files: Reference to existing similar implementations

🏷️ Labels Added

• api - API endpoints needed
• ui/ux - User interface components required
• attack-configuration - Attack setup functionality
• file-management - File upload/management for .hckmap files
• resource-management - Resource lifecycle management
• enhancement (retained)

👤 Assignment

• Assigned to: unclesp1d3r

The issue is now ready for implementation with a clear architectural approach that follows your existing codebase patterns. View the enhanced issue at: #659