*`)#

Note on Code Examples: This document contains Python/FastAPI/Pydantic code examples for reference. When implementing in Rails, translate these patterns to Ruby/Rails/ActiveModel equivalents using appropriate Rails conventions (controllers, models, concerns, serializers, etc.).

These endpoints support the Rails/Hotwire dashboard that human users interact with. They power views, forms, toasts, and live updates via Turbo Frames and Turbo Streams. Agents do not use these endpoints. All list endpoints must support pagination and query filtering.

🧭 These endpoints define the backend interface needed to support the user-facing views described in Phase 3 - Web UI Foundation. As you implement the frontend (Phase 3), be sure to reference this section to ensure every view or modal maps to a corresponding route here. We recommend annotating Stimulus controllers with source endpoint comments and may add cross-references in Phase 3 to maintain that alignment. Some amount of the frontend has already been implemented and will need to be maintained and refactored as the backend is implemented.

Table of Contents#

Web UI API (/api/v1/web/*)

Authentication and Profile#

Includes endpoints for administrator management of users and project access rights.

💡 Note: Users can only update their own name and email. Role assignment and project membership changes are restricted to admins.

Campaign Management#

For additional notes on the campaign management, see Campaign Notes.

Model Requirements#

To fully support UI ordering, user-friendly attack summaries, and richer campaign lifecycle controls, the following model-level fields must be added or updated:

Add Attack.position: int - numeric ordering field within a campaign task_id:model.attack.position
Add Attack.comment: Optional[str] - user-provided description for UI display task_id:model.attack.comment
Add Attack.complexity_score: Optional[int] - derived from keyspace or agent benchmarks, range 1-5 task_id:model.attack.complexity_score
Optionally evolve Campaign.active: bool into Campaign.state: Enum (draft, active, archived, etc.) to support lifecycle toggles and clear workflow states task_id:model.campaign.state_enum

These fields must be integrated into campaign detail responses, sortable/queryable in the DB layer, and respected in API output.

Implementation Tasks#

Note: Agent Configuration and Telemetry#

Some agent configuration and telemetry endpoints (e.g., fine-grained device toggles, temperature abort thresholds, hashcat backend flags) may not be fully supported by the current v1 Agent API.

These are earmarked for Phase 5 implementation when Agent API v2 is introduced.

Be sure to encapsulate such features behind feature flags or optional fields in the backend to avoid breaking compatibility.

Note: Agent Display Name Fallback#

logic:

display_name = agent.custom_label or agent.host_name

This fallback logic must be applied anywhere an agent is shown to the user. Include this behavior in both API response schemas and frontend component logic to ensure consistent display.

Attack Management#

For additional notes on the attack editor UX, see Attack Notes.

UX Design Goals#

These design goals are for the attack editor modal and should be applied to the data sent to the client. Though not exclusively API-related, these are important considerations for the API implementation and will be finalized in Phase 3 with the full user interface implementation. After adding the appropriate supporting functionality to the models and endpoints, Skirmish should add stub components for these views with TODO comments to ease implementing phase 3 frontend.

Common Editing Features#

Dynamically update keyspace and complexity score for unsaved changes task_id:attack.ux_estimate_unpersisted
Show these values in attack editor view like campaign detail view task_id:attack.ux_estimate_view
Warn and require confirmation when editing an exhausted or running attack task_id:attack.ux_edit_lifecycle_reset
Confirming edit resets attack to pending and triggers reprocessing task_id:attack.ux_edit_lifecycle_reset
Allow export/import of JSON files for Attack or Campaign (supports template reuse) task_id:attack.ux_export_import_json

Dictionary Attack UX#

See New Dictionary Attack Editor for more details.

Min/max length fields default to typical hash type range (e.g., 1-32) task_id:attack.ux_dictionary_length_defaults
Wordlist dropdown with search, sorted by last modified, includes entry count task_id:attack.ux_dictionary_wordlist_dropdown
"Modifiers" button group for non-expert users (e.g., + Change Case, + Substitute Characters) in dictionary attack editor (task_id:attack.ux_dictionary_modifiers)
Optional rule list dropdown for expert users task_id:attack.ux_dictionary_rule_dropdown
- This should be a Searchable Dropdown that allows the user to search for a rule by name and select one.
Support "Previous Passwords" as dynamic wordlist option task_id:attack.ux_dictionary_previous_passwords
- This will automatically generate a dynamic wordlist from the previous project's cracked passwords. When this option is select, the wordlist dropdown and the option for ephemeral wordlist should be hidden. The dynamic wordlist is not persisted and is generated on the fly when the attack is run or rerun.
Support ephemeral wordlist field with "Add Word" UI for small lists task_id:attack.ux_dictionary_ephemeral_wordlist
- This should be a Flowbite Text Input with a "+" button to add a new word. The words should be persisted in the attack resource file and used as a generated wordlist when the attack is run.

Mask Attack UX#

See New Mask Attack Editor for more details.

Add/remove inline mask lines (ephemeral mask list) task_id:attack.ux_mask_inline_lines
Validate mask syntax in real-time task_id:attack.ux_mask_syntax_validation
- This should follow hashcat's mask syntax restrictions. This applies to the mask input field implemented in task_id:attack.ux_mask_inline_lines and the validation should be triggered when the user leaves the input field.
Ephemeral mask list stored only with the attack, deleted when attack is removed task_id:attack.ux_mask_ephemeral_storage
Add/remove inline mask lines (ephemeral mask list) task_id:attack.ux_mask_inline_lines
- This should be a Flowbite Text Input with a "+" button to add a new word. The masks should be persisted in the attack resource file and used as a generated mask list when the attack is run.

Brute Force UX#

See New Brute Force Attack Editor for more details.

Checkbox UI for charset selection (Lowercase, Uppercase, Numbers, Symbols, Space) task_id:attack.ux_brute_force_charset_selection
- Each charset maps to a mask token for the ?1 character (i.e. ?l for lowercase, etc.). The user should be able to select one or more charsets and the selected charsets should be used to generate the mask.
Range selector for mask length (min/max) task_id:attack.ux_brute_force_length_selector
- This should be a Flowbite Range Slider and it is used to set the min_length and max_length of the the incremental attack.
- The max length is also used to set the number of ?1 tokens in the mask (see task_id:attack.ux_brute_force_mask_generation)
Automatically generate ?1?1?... style mask based on selected length task_id:attack.ux_brute_force_mask_generation
- The brute force attack is just a user friendly way to generate an increment attack with a mask. The mask is generated by the ?1 token which is repeated for the length of the maximum character length (defined by the max_length in task_id:attack.ux_brute_force_length_selector). The selected character types are used to set the tokens used in the custom character set 1 for the attack.
Derive ?1 charset from selected charsets (e.g., ?l?d for lowercase + digits) task_id:attack.ux_brute_force_charset_derivation
- This is determined from the character types chosen in task_id:attack.ux_brute_force_charset_selection and should be set as the custom_charset_1 for the attack.

Implementation Tasks#

Includes support for a full-featured attack editor with configurable mask, rule, wordlist resources; charset fields; and validation logic. Endpoints must power form-based creation, preview validation, reordering, and config visualization.

Note: See Attack Notes for more details on the attack editor UX and implementation.

All views should support SSE triggers or polling to allow dynamic refresh when agent-submitted updates occur.

GET /api/v1/web/attacks/ - List attacks (paginated, searchable) task_id:attack.list_paginated_searchable
POST /api/v1/web/attacks/ - Create attack with config validation task_id:attack.ux_created_with_validation
- This supports the creation of a new attack with validation of the attack's config using ActiveModel validations.
GET /api/v1/web/attacks/{id} - View attack config and performance task_id:attack.ux_view_config_performance
- This supports the display of the attack's config and performance information in a modal when the user clicks on an attack in the campaign detail view.
PATCH /api/v1/web/attacks/{id} - Edit attack task_id:attack.ux_edit_attack
- This supports the editing of the attack's config in a modal when the user clicks on an attack in the campaign detail view.
DELETE /api/v1/web/attacks/{id} - Delete attack task_id:attack.ux_delete_attack
- This deletes an attack from the campaign. The attack should be removed from the campaign. If the attack has not been started, it should be deleted from the database.
- If the attack has been started, it should be marked as deleted and the attack should be stopped.
  - Any ephemeral resources should be deleted from deleted attacks, but non-ephemeral resources should be unlinked from the attack.
POST /api/v1/web/attacks/validate - Return validation errors or keyspace estimate (see Core Algorithm Implementation Guide) task_id:attack.validate_errors_keyspace
GET /api/v1/web/attacks/{id}/performance - Return task/agent spread, processing rate, and agent participation for a given attack.
- Used to diagnose bottlenecks or performance issues by surfacing which agents worked the task, their individual speed, and aggregate throughput.
- Useful for verifying whether a slow campaign is due to insufficient agent coverage or unexpectedly large keyspace. task_id:attack.performance_diagnostics

Hash List Management#

Hash lists are a collection of hashes that can be used in a campaign. They are a fundemental core component of CipherSwarm and are the primary way to manage hashes within a project. When a hash list is added to the system, either through the upload of a file containing hashes or through the creation of a new hash list, the hashes are stored in the database as hash items and are associated with the hash list. When a campaign is created, the hash list can be selected and the hashes in the hash list will be the focus of the attacks. When an agent requests a task, which is a subset of an attack, the agent will receive a dynamically generated download file containing the uncracked hashes from the hash list in a format that is compatible with hashcat. As the agent processes the hashes, the agent will submit the cracked hashes back to the system and the system will update the hash list with the cracked hashes. If another agent successfully cracks a hash that is part of a hash list that is being worked by another agent, all agents working on the hash list will be notified and directed to download a zap list, which contains the hashes that have been cracked since the they downloaded the hash list. The agent portion of this process is handled by the Agent API, here we will be implementing the endpoints for the user interface to manage hash lists.

Since hash lists are one of the most sensitive components of the system, they are always restricted to a specific project and are never visible to other projects. This is enforced by the system and the user interface should reflect this restriction. If an attack successfully cracks a hash that appears in multiple hash lists across different projects, the hash item in each project will be updated with the found plaintext value, but it is not revealed to the user what attack found the plaintext (unlike when a hash is cracked in a campaign that is part of the user's project). This is to avoid leaking information about password reuse across multiple projects.

UX Design Goals#

Add POST /api/v1/web/hash_lists/ - Create a new hash list task_id:hash_list.create
GET /api/v1/web/hash_lists/ - List hash lists (paginated, searchable) task_id:hash_list.list_paginated_searchable
GET /api/v1/web/hash_lists/{id}/items - List hash items in hash list task_id:hash_list.list_items - This should return a paginated list of hash items in the hash list and should be searchable by hash value, plaintext, and status. The status is simply cracked or uncracked, depending on whether plaintext is found or not. The list should be exportable as TSV and CSV files.
GET /api/v1/web/hash_lists/{id} - View hash list task_id:hash_list.view
PATCH /api/v1/web/hash_lists/{id} - Update hash list task_id:hash_list.update
DELETE /api/v1/web/hash_lists/{id} - Delete hash list task_id:hash_list.delete

Save/Load Schema Design#

CipherSwarm should allow saving and loading of both individual Attacks and entire Campaigns via a custom JSON format. This will support backup, sharing, and preconfiguration workflows.

🔐 The exported format must include:

All editable fields of the attack or campaign, including position and comment
For campaigns: the order of attached attacks must be preserved
Any ephemeral word or mask lists used by an attack must be serialized as inline content
For linked non-ephemeral resources (wordlists, masks, rules), include their stable UUID (guid) for re-linking

🚫 The exported format must not include:

Project ID or User ID bindings
Internal database primary keys

📥 On import:

The backend must validate schema correctness
Rehydrate ephemeral resources directly
Look up non-ephemeral resources by GUID (guid)
Prompt the user or fail gracefully if a GUID reference does not resolve

This schema should be versioned and tested against a validation spec.

A new guid: UUID field must be added to the AttackResourceFile model to support this. The GUID should be unique, stable across sessions, and used as the canonical identifier for serialization workflows. It should be generated using uuid4() at the time the resource is first created, and must remain immutable and internal-only (not exposed to Agent APIs).

If a resource referenced by GUID cannot be matched during import (either due to deletion or lack of permission), the user must be prompted with three fallback options:

Select a Replacement - Choose a compatible resource of the same resource_type from a dropdown
Skip Affected Attack - Import the rest of the campaign, omitting attacks missing required resources
Abort Import - Cancel the import entirely

All fallback logic should be implemented server-side with support for frontend prompting.

Ephemeral Resources#

Attacks can support ephemeral resources that can be created and edited within the attack editor. These resources are still persisted to the database, but they are stored as part of an AttackResourceFile record as a JSON structure, and are not visible in the Resource Browser or available for reuse in other attacks. They are deleted when the attack is deleted, they do not have a backing file in S3, and they are exported inline if the attack is exported within the same JSON file. The Agent API will provide a non-signed URL to agents to access these resources when the attack is running and they are downloaded directly from CipherSwarm, rather than the MinIO service.

🧩 Extended Implementation Tasks#

These tasks expand the attack editing interface and logic to support contextual UIs, one-off resources, and user-friendly modifiers without exposing raw hashcat details.

Implement POST /api/v1/web/attacks/estimate to return keyspace + complexity score for unsaved attack input task_id:attack.estimate_unpersisted (see Phase 2 Implementation Tasks)
Add edit-protection logic to warn if attack is running or completed before allowing edit (Web UI API) task_id:attack.edit_protect
Support ephemeral inline wordlists (multiple add word fields) stored in memory or DB during attack creation, deleted when the attack is deleted. (Web UI API) task_id:attack.ephemeral_wordlist
Support ephemeral inline masks (add mask line interface) with same lifecycle behavior task_id:attack.ephemeral_masklist (see section Ephemeral Resources above)
task_id:attack.modifier_ui_to_rules Implement "Modifiers" UI: Map UI modifier buttons to rule file UUIDs for dictionary attacks (see notes/ui_screens/new_dictionary_attack_editor.md, attack.md). Ensure the mapping is robust, testable, and extensible. Add tests for all supported modifiers.
Dictionary attack UI must support: min/max length, searchable wordlist dropdown (sorted by last modified), option to use dynamic wordlist from previous project cracks task_id:attack.dictionary_ui_controls
- See Dictionary Attack UX for more details.
Brute force UI must allow checkbox-driven charset selection, range selector, and generate corresponding ?1?1?... style masks and ?1 custom charset task_id:attack.brute_force_ui_logic (strong typing enforced)
Add support to export any single Attack or entire Campaign to a JSON file task_id:attack.export_json
Add support to load campaign or attack JSON file and prefill the editor task_id:attack.import_json_schema
- See Save/Load Schema Design for more details.

The attack editor must support a modal-based, multi-form interface with per-attack-type customization. It should dynamically update keyspace estimates and complexity scores as the user changes input.

⚙️ The editor must show real-time keyspace and complexity values, even for non-persisted attacks. Backend support is needed for live estimation.
⚠️ Editing an attack that is already running or exhausted must trigger a confirmation prompt and reset the state if confirmed. This restarts the attack lifecycle.
✍️ User-facing options should be simplified (e.g. "+ Change Case") and map to hashcat rule resources internally.
🔁 Certain attack types (e.g., dictionary, brute force) must support one-off word/mask lists that are ephemeral and attack-local.

Agent Management#

For additional notes on the agent management, see Agent Notes.

🧩 UX Design Goals#

🖥️ Agent List View#

Everyone can see all agents and their state
Admin-only gear menu (Disable Agent / View Details)
Columns:
- Agent Name + OS
- Status
- Temp (°C) and Utilization (avg of enabled devices)
- Current and Average Attempts/sec
- Current Job (Project, Campaign, Attack)

➕ Agent Registration#

Modal to enter label and select Projects (multi-toggle)
- Upon creating a new agent, the UI must immediately display the generated token for copy/paste. Tokens are only shown once.
Upon save, display generated token to admin

⚙️ Agent Detail Tabs#

🔧 Settings

display_name = agent.custom_label or agent.host_name
Toggle: Enabled/Disabled
Agent Update Interval (sec, default randomized 1-15)
Toggle: Use Native Hashcat (sets AdvancedAgentConfiguration.use_native_hashcat = true)
Toggle: Enable Additional Hash Types (--benchmark-all)
List: Project assignment toggles
Static: OS, IP, Signature, Token

🖥️ Hardware

List of backend devices from --backend-info
Toggle each device on/off → updates backend_device
Device toggling prompts: Apply now / Next Task / Cancel if task is running
Show gray placeholder if no devices reported yet
HW Settings:
- --hwmon-temp-abort (note only, default to 90°C)
  - Note: This field is not yet supported by the v1 Agent API, but could be added safely to AdvancedAgentConfiguration as an optional key. The agent will ignore unknown fields.
- OpenCL Device Type selector (opencl_devices)
Backend toggles: CUDA, HIP, Metal, OpenCL → affect --backend-ignore-*

📈 Performance

Line chart of DeviceStatus.guess_rate over time (8hr window)
Donut chart per device within card: Utilization as a percentage (or N/A)
Live updating via SSE

🪵 Log

Timeline of AgentError entries
Color-coded severity
Fields: message, code, task link, details

🧠 Capabilities

Pulls from HashcatBenchmark
Table (rollup view): Toggle / Hash ID / Name / Speed / Category
Expandable rows per device
Filterable + searchable
Caption with benchmark timestamp
Header button to trigger benchmark (sets agent.state = pending)

🧩 Implementation Tasks#

Includes real-time updating views, hardware configuration toggles, performance monitoring, and error visibility. Most endpoints should use JSON requests and SSE triggers to refresh data without full page reloads. should be supported on list and detail views for dynamic agent status refresh.*

GET /api/v1/web/agents/ - List/filter agents task_id:agent.list_filter
- This will display a paginated, filterable datatable of all agents, with search and state filter. Used for the main agent management view. task_id:agent.list_filter
GET /api/v1/web/agents/{id} - Detail view task_id:agent.detail_view
- This will display a detailed view of the agent as described in the Agent Detail Tabs section.
PATCH /api/v1/web/agents/{id} - Toggle enable/disable task_id:agent.toggle_state
- This will be a toggle in the list of agents that changes the agent's enabled state and prevents the agent from picking up new tasks.
POST /api/v1/web/agents/{id}/requeue - Requeue failed task task_id:agent.manual_requeue
GET /api/v1/web/agents/{id}/benchmarks - View benchmark summary task_id:agent.benchmark_summary
- This will display a summary of the agent's benchmark results as described in the Agent Detail Tabs section. See also Agent Benchmark Compatibility for more details.
POST /api/v1/web/agents/{id}/test_presigned - Validate URL access task_id:agent.presigned_url_test

Resource Browser#

CipherSwarm uses AttackResourceFile objects to represent reusable cracking resources such as mask lists, wordlists, rule files, and custom charsets. All uploads go through the CipherSwarm backend, which creates the database record and issues a presigned S3 upload URL. No object in storage should exist without a matching DB entry. Each file includes a declared resource_type that drives editor behavior, validation rules, and allowed usage in attacks.

Line-oriented resources (masks, rules, small wordlists) may be edited interactively in the Web UI. Each line is validated individually and exposed via a dedicated endpoint. Larger files must be downloaded, edited offline, and reuploaded.

🧩 Implementation Tasks#

🧠 Attack resource files share a common storage and metadata model, but differ significantly in validation, UI affordances, and where they are used within attacks. To support this diversity while enabling structured handling, each resource must declare a resource_type, which drives editor behavior, validation rules, and attack compatibility.

Supported resource_type values (Rails implementation should use an enum or string constants):

# app/models/attack_resource_file.rb (example structure for reference)
class AttackResourceFile < ApplicationRecord
  enum resource_type: {
    mask_list: 'mask_list',
    rule_list: 'rule_list',
    word_list: 'word_list',
    charset: 'charset',
    dynamic_word_list: 'dynamic_word_list' # Read-only, derived from cracked hashes
  }
end

Each AttackResourceFile model should include these attributes:

# Rails model attributes (for reference)
# resource_type: String (enum)
# used_for_modes: Array # Enforced compatibility with hashcat attack modes (stored as JSON or array column)
# line_encoding: String # "ascii" or "utf-8" - Affects validation + editor behavior
# line_format: String # "freeform", "mask", "rule", "charset"
# source: String # "upload", "generated", "linked"

Editor behavior must respect the declared type:

Resource TypeEditable?Line FormatEncodingNotes
`mask_list`	✅	mask syntax	ASCII	one per line, validated mask syntax
`rule_list`	✅	rule grammar	ASCII	strict per-line validation
`word_list`	✅*	freeform	UTF-8	loose rules, allow unicode, strip control
`charset`	✅	charset def	ASCII	e.g. `custom1 = abc123`, used in attacks
`dynamic_word_list`	❌	N/A	UTF-8	read-only, generated from cracked hashes

(*) Editing of large word lists may be disabled based on configured size thresholds.

Uploads must be initiated via CipherSwarm, which controls both presigned S3 access and DB row creation. No orphaned files should exist. The backend remains source of truth for metadata, content type, and validation enforcement.

🚨 Validation errors for resource line editing should follow Rails conventions. Return 422 Unprocessable Entity with structured JSON for validation errors:

Example response for per-line validation:

{
  "errors": [
    {
      "line_index": 3,
      "content": "+rfoo",
      "valid": false,
      "message": "Unknown rule operator 'f'"
    },
    {
      "line_index": 7,
      "content": "?u?d?l?l",
      "valid": false,
      "message": "Duplicate character class at position 3"
    }
  ]
}

Suggested Rails serializer structure (for reference):

# Rails serializer or view model (example)
class ResourceLineValidationError
  attr_accessor :line_index, :content, :valid, :message

  def initialize(line_index:, content:, valid: false, message:)
    @line_index = line_index
    @content = content
    @valid = valid
    @message = message
  end

  def as_json(options = {})
    {
      line_index: @line_index,
      content: @content,
      valid: @valid,
      message: @message
    }
  end
end

This should be returned from:

GET /resources/{id}/lines?validate=true
PATCH /resources/{id}/lines/{line_id} if content is invalid

For valid input, return 204 No Content or the updated data, which controls both presign + DB insert. No orphaned files should exist. The backend remains source of truth for metadata, content type, and validation enforcement.

🔒 All uploaded resource files must originate from the CipherSwarm backend, which controls presigned upload URLs and creates the corresponding database entry in the AttackResourceFile model (located in app/models/attack_resource_file.rb). There should never be a case where a file exists in the object store without a corresponding DB row. The S3-compatible backend is used strictly for offloading large file transfer workloads (uploads/downloads by UI and agents), not as an authoritative metadata source.

💡 The UI should detect resource type and size to determine whether inline editing or full download is allowed. The backend should expose content metadata to guide this decision, such as line_count, byte_size, and resource_type. The frontend may display masks, rules, and short wordlists with line-level controls; long wordlists or binary-formatted resources must fall back to download/reupload workflows.

Includes support for uploading, viewing, linking, and editing attack resources (mask lists, word lists, rule lists, and custom charsets). Resources are stored in an S3-compatible object store (typically MinIO), but CipherSwarm must track metadata, linkage, and validation. Users should be able to inspect and edit resource content directly in the browser via web-based interactions.

🔐 Direct editing is permitted only for resources under a safe size threshold (e.g., < 5,000 lines or < 1MB). Larger files must be downloaded, edited offline, and reuploaded. This threshold should be configurable via an environment variable or application setting (e.g., RESOURCE_EDIT_MAX_SIZE_MB, RESOURCE_EDIT_MAX_LINES) to allow for deployment-specific tuning.

Line-Oriented Editing#

For eligible resource types (e.g., masks, rules, short wordlists), the Web UI should support a line-oriented editor mode:

Each line can be edited, removed, or validated individually.
Validation logic should be performed per line to ensure syntax correctness (e.g., valid mask syntax, hashcat rule grammar).
Inline editing should be driven via Stimulus controllers making fetch requests to the backend.

Suggested line-editing endpoints:

GET /api/v1/web/resources/{id}/lines - Paginated and optionally validated list of individual lines task_id:resource.line_api_endpoints
POST /api/v1/web/resources/{id}/lines - Add a new line task_id:resource.add_line
PATCH /api/v1/web/resources/{id}/lines/{line_id} - Modify an existing line task_id:resource.update_line
DELETE /api/v1/web/resources/{id}/lines/{line_id} - Remove a line task_id:resource.delete_line

The backend should expose a ResourceLine representation (Rails serializer or view model example):

# Rails view model or serializer (for reference)
class ResourceLine
  attr_accessor :id, :index, :content, :valid, :error_message

  def as_json(options = {})
    {
      id: @id,
      index: @index,
      content: @content,
      valid: @valid,
      error_message: @error_message
    }
  end
end

These may be backed by temporary parsed representations for S3-stored resources, cached in memory or a staging database table for edit sessions.

UX Support and Utility#

Purpose#

This section defines endpoints used by the frontend to dynamically populate UI elements, fetch partials, and support dropdowns, summaries, and metadata helpers that don't belong to a specific resource type.

Implementation Tasks#

GET /api/v1/web/modals/agents - Populate agent dropdowns task_id:ux.populate_agents
- This should return a list of agents with their name and status, based on the Agent model. - Any authenticated user should be able to see all agents.
GET /api/v1/web/modals/resources - Populate resource selectors (mask, wordlist, rule) task_id:ux.populate_resources
- This should return a list of resources with their name, and type, based on the AttackResourceFile model. It does not show dynamic wordlists or ephemeral resources and only shows resources that are linked to the current project (based on the Project context created in task_id:auth.get_context) or are unrestricted, unless the user is an admin. Should allow for filtering by resource type and name, sorted by most recently modified.
GET /api/v1/web/modals/hash_types - Populate hash type dropdowns task_id:ux.populate_hash_types
- This should return a list of hash types with their name and numeric mode, based on the HashMode model. It should be filterable by name and mode and return a nullable confidence score for the guess service if the guess service was involved in populating the dropdown (to support the hash type override UI in task task_id:guess.hash_type_override_ui). Sort by confidence score descending (unless it is None), then by mode ascending.
GET /api/v1/web/dashboard/summary - Return campaign/task summary data as structured JSON containing aggregated data for the various dashboard widgets task_id:ux.summary_dashboard - see docs/v2_rewrite_implementation_plan/notes/ui_screens/dashboard-ux.md for the expected structure and widgets - See docs/v2_rewrite_implementation_plan/notes/ui_screens/dashboard-ux.md for the complete description of the dashboard and the widgets that should be supported.
GET /api/v1/web/health/overview - System health snapshot (agents online, DB latency, task backlog) task_id:ux.system_health_overview - This is more focused on the functionality of the system than the components and should be a overview of the number of agents online, the number of campaigns, tasks, and hash lists, as well as their current status and performance metrics and any errors that have occurred with any of the various agents, campaigns, tasks, and hash lists. See docs/v2_rewrite_implementation_plan/notes/ui_screens/health_status_screen.md for the complete description of the health status screen and the components that should be supported.
GET /api/v1/web/health/components - Detailed health of core services (MinIO, Redis, DB) task_id:ux.system_health_components
- This should include the detailed health of the MinIO, Redis, and DB services and their status, including latency and errors. See Health Status Screen Notes for the complete description of the health status screen and the components that should be supported.
Implement basic cashews cache for the health overview and components task_id:ux.system_health_cache - This should be configured using the cashews cache decorator and should be configured to cache the health overview and components for 60 seconds. The cache should support memory and redis backends, with the memory backend being the default. It should be configured in app/core/config.py as settings.CACHE_CONNECT_STRING, defaulting to mem://?check_interval=10&size=10000, and the connection string should be passed to cache.setup in app/main.py. Caching should be disabled in tests.
GET /api/v1/web/modals/rule_explanation - Return rule explanation data task_id:ux.rule_explanation_modal
- This should return data to populate a rule explanation modal, which is a modal that explains the rule syntax for the selected rule. It should be a modal that is triggered by a button in the UI. - See docs/v2_rewrite_implementation_plan/notes/specific_tasks/rule_explanation.md

Crackable Uploads#

To streamline the cracking workflow for non-technical users, we should support uploading raw data (files or hash datas) and automating the detection, validation, and campaign creation process. The system must distinguish between:

File uploads (e.g., .zip, .docx, .pdf, .kdbx) that require binary hash extraction
Pasted or raw hash text (e.g., lines from /etc/shadow, impacket's secretsdump, Cisco config dumps)

In the case of pasted hashes, the system should automatically isolate the actual hash portion, remove surrounding metadata, and sanitize formatting issues. This includes stripping login expiration flags from shadow lines or extracting just the hash field from NTLM pairs.

Use cases include:

Uploading a file (e.g., .zip, .pdf, .docx) to extract hashes
Pasting a hash from a source like /etc/shadow, even if it includes surrounding shadow metadata

This process should:

Extract or isolate the hash automatically
Perform validation on the extracted hash (type, syntax, format)
Prevent campaign creation if the hash is malformed or would fail in hashcat
Detect the hash type
Validate hashcat compatibility
Provide preview/feedback of what will be created
Automatically create:
- A HashList
- A Campaign
- One or more preconfigured Attacks

Users can then launch the campaign immediately or review/edit first.

Implementation Tasks#

Live Event Feeds (Server-Sent Events)#

These endpoints provide Server-Sent Events (SSE) streams that Stimulus controllers can subscribe to for real-time trigger notifications, prompting the client to issue targeted fetch requests or Turbo Stream updates. No data is pushed directly via SSE streams - only lightweight notification signals (e.g., { "trigger": "refresh" }) to inform the client that updated content is available.

SSE is preferred over WebSockets for this use case because:

Simpler architecture: No Redis dependency or complex pub/sub infrastructure
Better reliability: Browser handles reconnection automatically
Easier testing: No external dependencies or connection management
HTTP-based: Works through proxies and firewalls
Perfect fit: One-way notifications are exactly what SSE is designed for

Core Infrastructure#

✅ Rails ActionController::Live with streaming for SSE endpoints
✅ In-memory event broadcasting (no Redis required)
✅ JavaScript EventSource client-side support via Stimulus controllers
✅ Devise JWT-based auth and project scoping

Event Triggers by Feed#

campaigns: On Attack, Task, or Campaign state change; CrackResult submission.
agents: On agent heartbeat, performance update, or error report.
toasts: On new CrackResult; displayed via UI toast notification.

Implementation Tasks (SSE Event System)#

Core Event Infrastructure#

Create event broadcasting service (app/core/services/event_service.py) task_id:sse.event_service
- Implement in-memory event broadcaster with topic-based subscriptions task_id:sse.memory_broadcaster
- Add event listener registration/deregistration task_id:sse.listener_management
- Support project-scoped event filtering task_id:sse.project_scoping

SSE Endpoint Routes#

Each route provides an SSE stream for specific event types:

GET /api/v1/web/live/campaigns - Campaign/attack/task state changes task_id:sse.campaign_feed
GET /api/v1/web/live/agents - Agent status, performance, and error updates task_id:sse.agent_feed
GET /api/v1/web/live/toasts - New crack results and system notifications task_id:sse.toast_feed

Event Broadcasting Integration#

Create service-layer event triggers task_id:sse.service_triggers
- Trigger campaign events on Attack, Task, Campaign updates task_id:sse.campaign_triggers
- Trigger agent events on Agent, DeviceStatus, AgentError changes task_id:sse.agent_triggers
- Trigger toast events on CrackResult submission task_id:sse.toast_triggers

Authorization & Security#

Enforce JWT authentication on SSE connections task_id:sse.jwt_auth
Implement project-based event filtering task_id:sse.project_filtering
Add connection timeout and cleanup task_id:sse.connection_cleanup

Event Message Format#

Standard lightweight event format:

{
  "trigger": "refresh",
  "timestamp": "2024-01-01T12:00:00Z"
}

Optional targeted events:

{
  "trigger": "refresh",
  "target": "campaign",
  "id": 123
}

Supporting Infrastructure#

File Layout#

app/
├── controllers/
│ └── api/
│ └── v1/
│ └── web/
│ └── live_controller.rb # SSE endpoints for /api/v1/web/live/*
├── services/
│ └── event_service.rb # In-memory event broadcasting

Module Responsibilities#

api/v1/web/live_controller.rb
- Rails SSE route handlers using ActionController::Live and streaming
- Authentication via before_action with Devise
- Project scoping and event filtering
services/event_service.rb
- In-memory event broadcaster
- Topic-based subscription management
- Event listener lifecycle management
- Project-scoped event filtering

Migration from WebSocket Implementation#

Remove WebSocket dependencies and Redis pub/sub code task_id:sse.cleanup_websocket
Update existing broadcast functions to use new event service task_id:sse.migrate_broadcasts
Remove WebSocket-related gems from Gemfile task_id:sse.remove_websocket_deps
Update tests to use SSE instead of WebSocket connections task_id:sse.update_tests

Documentation Updates#

With the many changes to the API, we need to update the documentation to reflect the changes. These changes go beyond just the SSE implementation, but also include the new endpoints and changes to the existing endpoints, as well as changes to the UI and user flows documented in docs/v2_rewrite_implementation_plan/side_quests/salvage_templates.md and docs/v2_rewrite_implementation_plan/notes/user_flows_notes.md. The changes to be made are:

Update the architecture documentation to reflect the changes. (found in docs/architecture/*.md)
Update the API reference documentation to reflect the structure of the API and the endpoints that are available. (found in docs/api/overview.md and docs/development/api-reference.md)
Update the user guide to reflect the changes. (found in docs/user-guide/*.md)
Update the developer guide to reflect the changes. (found in docs/development/*.md)
Update the getting started guide to reflect the changes. (found in docs/getting-started/*.md)
Update the troubleshooting guide to reflect the changes. (found in docs/user-guide/troubleshooting.md) - The primary audience for this guide is the administrator configuring the system, and the end user trying to figure out why their campaign is behaving as expected. It is not for developers and each section should be a single topic with a clear title and a description of the problem and the solution.
Update the FAQ to accurately reflect the current state of the system. (found in docs/user-guide/faq.md)

Additional Tasks#

Add robust unit tests for KeyspaceEstimator covering all attack modes and edge cases
Ensure all estimation logic (AttackEstimationService, endpoints, tests) uses strong typing (ActiveModel validations, enums, value objects) instead of hashes/untyped data for attack/resource parameters

Web UI API (/api/v1/web/*)#

Table of Contents#

Authentication and Profile#

Campaign Management#

Model Requirements#

Implementation Tasks#

Note: Agent Configuration and Telemetry#

Note: Agent Display Name Fallback#

Attack Management#

UX Design Goals#

Common Editing Features#

Dictionary Attack UX#

Mask Attack UX#

Brute Force UX#

Implementation Tasks#

Hash List Management#

UX Design Goals#

Save/Load Schema Design#

Ephemeral Resources#

🧩 Extended Implementation Tasks#

Agent Management#

🧩 UX Design Goals#

🖥️ Agent List View#

➕ Agent Registration#

⚙️ Agent Detail Tabs#

🔧 Settings

🖥️ Hardware

📈 Performance

🪵 Log

🧠 Capabilities

🧩 Implementation Tasks#

Resource Browser#

🧩 Implementation Tasks#

Line-Oriented Editing#

UX Support and Utility#

Purpose#

Implementation Tasks#

Crackable Uploads#

Implementation Tasks#

Live Event Feeds (Server-Sent Events)#

Core Infrastructure#

Event Triggers by Feed#

Implementation Tasks (SSE Event System)#

Core Event Infrastructure#

SSE Endpoint Routes#

Event Broadcasting Integration#

Authorization & Security#

Event Message Format#

Supporting Infrastructure#

File Layout#

Module Responsibilities#

Migration from WebSocket Implementation#

Documentation Updates#

Additional Tasks#

Web UI API (`/api/v1/web/*`)#