System Requirements Document for local-test

1. Introduction

local-test is a local credential-testing harness for a security laboratory. It sends HTTP/API requests from a local test target through an attempt controller to a candidate generator, a worker pool, a deliberately vulnerable local test authentication service, and a result/log output. The harness exists so that a lab operator can measure how weak a set of laboratory credentials is, using a target and a vulnerable test authentication service that the operator controls.

The product is a measuring instrument, not a general-purpose tool. It counts attempts per second, tracks a queue of pending, successful, and failed attempts, and returns a single verdict per candidate: the laboratory service accepted it or rejected it. Its audience is technical, hands-on, and slightly adversarial in spirit — people who want to feel the machine working: rates, counters, queues, accept/reject verdicts.

The harness is explicitly scoped to laboratory use. It is not for use against systems the operator does not control, and its password lists are locally generated test lists.

2. System Overview

local-test is delivered as a first-party web application backed by a local service. The operator configures a run with a target they control, test username(s), a locally generated test password list, and optional concurrency settings. The harness then generates or reads candidate passwords, submits each candidate to the deliberately vulnerable local test authentication service, analyzes the controlled test application's response to decide accept or reject, and reports attempts/second, number tested, the successful laboratory credential, error counts, and runtime/logs.

Current delivery covers the full laboratory pipeline: input configuration, candidate generation, attempt execution, response analysis, concurrency and queue management, and results/logging. Run state and attempt results are retained so that queue processing and later result review are possible.

Actors:

• Security Lab Operator — runs credential-strength experiments against a deliberately vulnerable local test authentication service they control.
• Test Harness Maintainer — owns the harness internals: candidate generator, attempt engine, response analyzer, worker pool, and central queue.

Narrow exclusions:

• The harness is not for use against systems the operator does not control.
• Password lists are locally generated test lists.
• Concurrency settings are optional; the harness must run without them.

2a. Product Interpretation and Delivery Boundary

local-test is a local instrument. Everything it measures happens against a target the operator controls and a deliberately vulnerable local test authentication service that the operator stands up for the experiment. The harness never reaches outside that boundary, and it does not attempt to discover, enumerate, or attack anything the operator has not explicitly supplied as a target.

The application owns the run lifecycle: configuration, candidate generation, attempt submission, response analysis, queue tracking, and result reporting. The operator owns the target and the vulnerable test authentication service; the harness treats them as external systems it is pointed at, not as things it provisions. The password list is locally generated test material supplied by the operator.

Access is open. The Landing, Run Setup, Candidates, Attempt Runner, Response Analyzer, Queue Monitor, and Results surfaces are reachable without an account, because the harness runs on the operator's own bench against their own laboratory service. No account, invitation, or provisioning step is part of the current product.

Everything described in this document is current. There is no accepted future horizon beyond the current laboratory pipeline.

2b. Source Content Inventory

Not applicable. No reference directive in this project declares a content_source.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous first impression of the local credential-testing harness. Explains that it is a laboratory instrument for measuring credential strength against a deliberately vulnerable local test authentication service the operator controls. States the controlled test workflow: Input → Candidate Generator → Worker Pool → Local Test Auth Server → Response Analyzer → Result/Log. States the laboratory boundary plainly: target you control, locally generated test password list, not for use against systems you do not control.
• Primary actions: Enter the harness and begin configuring a run (Run Setup). Read the pipeline explanation.
• Supporting actions: Read the laboratory boundary statement; read the input requirements (target, test username(s), locally generated test password list, optional concurrency settings).
• Domain entities: Run (conceptual), pipeline stage, laboratory boundary.
• Component responsibilities: Oversized circular gauge cluster occupying the right two-thirds of the viewport — a large central dial reading attempts/second with the amber needle, flanked by two smaller bezels for "tested" and "accepted". Left third holds the product name in condensed uppercase at clamp(44px, 9vw, 128px), stacked over a ruled target line, with a single amber "Arm run" control pinned beneath it. Behind the gauges, faint topographic contour lines and a very low-opacity brushed-titanium texture. The pipeline is rendered as an engraved schematic strip — six numbered nodes on a hairline rail with a travelling amber pulse that marks which stage is currently executing. No centred headline, no subtext block, no blue button, no gradient blob.
• States:
  • Loading: Gauges render at zero with needles at rest; the schematic strip shows all six nodes unlit.

• Empty: No run is armed. The central dial reads 0.0 attempts/sec; "tested" and "accepted" bezels read 0. The "Arm run" control is the only active control.
• Success: The operator proceeds to Run Setup; the hero remains as the entry surface.
• Error: If the harness backend is unreachable, the gauge cluster renders in a static resting state with a muted steel notice that the local service is not responding, and the "Arm run" control is disabled.
• Recovery: The notice clears and the control re-enables when the local service responds again.

Run Setup

• Information/state: The configuration surface for a single run. Displays the four accepted inputs: the target the operator controls, test username(s), the locally generated test password list, and optional concurrency settings. Shows the current values of each field and whether concurrency settings have been supplied.
• Primary actions: Supply the target the operator controls. Supply test username(s). Supply the locally generated test password list. Optionally supply concurrency settings. Start the run.
• Supporting actions: Edit any supplied value before starting. Clear a supplied value. Review the laboratory boundary reminder.
• Domain entities: Run configuration, target, test username, test password list, concurrency settings.
• Component responsibilities: Ruled instrument module with a numbered header and a status lamp. Each input is a ruled data row with an 11px uppercase Saira Condensed micro-label at +0.14em tracking above the value. The target row carries the ruled target line treatment from the hero. Concurrency settings are presented as an optional row, visually distinct from the required rows. The start control is a single amber instrument control.
• States:
  • Loading: Fields render in a disabled state while the local service is contacted.
  • Empty: No target, no usernames, no password list, no concurrency settings. The start control is disabled.
  • Success: All required inputs are present; the start control is enabled and the run begins.

• Error: If the target is missing, no test username is supplied, or no locally generated test password list is supplied, the corresponding ruled row shows a muted steel inline message and the start control stays disabled. If the target is not reachable as a controlled local test target, the run does not start and the row reports the failure.
• Recovery: Correcting the offending row clears its message and re-enables the start control.

Candidates

• Information/state: The candidate password set for the run. Shows how candidates were produced or read, and which approach was used: dictionary, rule-based, or exhaustive combinations. Shows the count of candidates available to the queue.
• Primary actions: Generate candidate passwords. Read candidate passwords from a supplied locally generated test password list. Choose the generation approach (dictionary, rule-based, exhaustive combinations).
• Supporting actions: Inspect the generated candidate set. Regenerate candidates before a run starts.
• Domain entities: Candidate password, generation approach (dictionary, rule-based, exhaustive combinations), locally generated test password list.
• Component responsibilities: Numbered instrument module with a ruled header and a status lamp. Approach selection is a ruled row set, one row per approach, each with a micro-label. The candidate count is an oversized tabular condensed numeral. The candidate list is a ruled data table with tabular numerals and a 1px baseline under each entry.
• States:
  • Loading: The candidate count renders as a resting dial while generation runs.
  • Empty: No candidates generated or read yet. The count reads 0 and the approach rows are selectable.
  • Success: Candidates are available; the count reflects the generated or read set and the module status lamp lights.
  • Error: If the supplied locally generated test password list cannot be read, or an approach produces no candidates, the module reports the failure in muted steel and the count stays at its last known value.
  • Recovery: Supplying a readable list or selecting a different approach clears the failure and repopulates the count.

Attempt Runner

• Information/state: The submission surface. Shows each candidate being sent to the deliberately vulnerable local test authentication service, and records whether the laboratory service accepts or rejects it. Shows the current submission position within the candidate set.
• Primary actions: Submit each candidate to the deliberately vulnerable local test authentication service. Record the laboratory service's accept or reject outcome for each candidate.
• Supporting actions: Observe the in-flight candidate. Observe the recorded accept/reject outcome per candidate.
• Domain entities: Attempt, candidate, laboratory service response, accept outcome, reject outcome.
• Component responsibilities: Numbered instrument module with a ruled header and a status lamp. The in-flight candidate is shown as a ruled row with tabular condensed numerals. Accept outcomes carry the amber instrument signal; reject outcomes render in desaturated warm grey. The module sits on the engraved schematic rail between the Candidate Generator node and the Local Test Auth Server node.
• States:
  • Loading: The module status lamp pulses amber while attempts are in flight.
  • Empty: No run is active; no candidate is in flight and no outcome is recorded.
  • Success: Each candidate has a recorded accept or reject outcome from the laboratory service.
  • Error: If the deliberately vulnerable local test authentication service does not respond, the attempt is recorded as an error rather than as an accept or reject, and the error count increments.
  • Recovery: When the laboratory service responds again, submission resumes from the queue and the error count holds its accumulated value.

Response Analyzer

• Information/state: The verdict surface. Shows how success or failure was determined from the controlled test application's response, using HTTP status codes and response contents rather than status codes alone. Shows the analyzer's reasoning for the current verdict.
• Primary actions: Determine success or failure from the controlled test application's response. Inspect the HTTP status code and response contents that produced the verdict.
• Supporting actions: Review the analyzer's decision for a specific attempt. Adjust analyzer logic so results are accurate rather than false-positive-prone.
• Domain entities: HTTP status code, response contents, accept verdict, reject verdict, false positive.
• Component responsibilities: Numbered instrument module with a ruled header and a status lamp. The verdict is rendered as a single amber pulse on the matched row when accepted, then holds; rejections render in desaturated warm grey. Status code and response contents are shown as ruled data rows with tabular condensed numerals and micro-labels.
• States:
  • Loading: The verdict row renders in a resting state while the response is analyzed.
  • Empty: No response has been analyzed yet.
  • Success: A verdict is determined and displayed, with the status code and response contents that produced it.
  • Error: If the response cannot be analyzed — for example, a status code alone would be ambiguous — the analyzer reports the ambiguity rather than asserting a verdict, and the attempt is not counted as accepted.
  • Recovery: Once the response contents resolve the ambiguity, the verdict is determined and displayed.

Queue Monitor

• Information/state: The central queue. Tracks pending, successful, and failed attempts as the worker pool processes candidates. Shows queue depth and the distribution across the three states.
• Primary actions: Observe the worker pool processing candidates. Observe pending, successful, and failed attempts in the central queue.
• Supporting actions: Observe workers claiming candidates. Observe the queue drain as the run proceeds.
• Domain entities: Worker pool, central queue, pending attempt, successful attempt, failed attempt.
• Component responsibilities: Full-width horizontal strip of stacked tick marks showing pending, successful, and failed as three distinct bands. Tick marks light in sequence as workers claim candidates. Queue depth is an oversized tabular condensed numeral with an 11px uppercase micro-label at +0.14em tracking. Active queue states carry the amber instrument signal.
• States:
  • Loading: The strip renders with all tick marks unlit while the queue is populated.
  • Empty: No run is active; all three bands are unlit and queue depth reads 0.
  • Success: The queue drains to zero pending, with successful and failed bands holding their final counts.
  • Error: If a worker fails, the affected attempt moves to the failed band and the error count increments.
  • Recovery: The worker pool continues processing the remaining pending candidates; the failed band retains its count.

Results

• Information/state: The run's spec-sheet record. Shows attempts/second, number tested, the successful laboratory credential, error counts, and runtime/logs.
• Primary actions: Review attempts/second. Review number tested. Review the successful laboratory credential. Review error counts. Review runtime/logs.
• Supporting actions: Read the log entries for the run. Identify the successful laboratory credential on its own full-width amber-ruled line.
• Domain entities: Attempts/second, number tested, successful laboratory credential, error count, runtime, log entry.
• Component responsibilities: Engraved spec-sheet table with ruled rows and tabular condensed numerals. The successful laboratory credential is called out on its own full-width amber-ruled line. Attempts/second is presented as a dial readout consistent with the hero gauge cluster. Runtime/logs render as ruled log rows with tabular numerals and micro-labels.
• States:
  • Loading: Readouts render at rest while the run's final figures are assembled.
  • Empty: No run has completed; all readouts read zero and the log is empty.
  • Success: All five result figures are present, and the successful laboratory credential is called out on its amber-ruled line.
  • Error: If no candidate was accepted, the successful laboratory credential line reads as no laboratory credential accepted, in desaturated warm grey, and the error count and logs remain available.
  • Recovery: Starting a new run replaces the readouts and logs with the new run's figures.

3. Functional Requirements

FR-1 — Local credential-testing harness pipeline As a Security Lab Operator, I should have a local credential-testing harness that sends HTTP/API requests from a local test target through an attempt controller to a candidate generator, worker pool, local test auth server, and result/log output, so that the laboratory pipeline runs end to end.

• Provenance: explicit
• Trigger/input: The operator starts a run against a target they control.
• Observable result: HTTP/API requests travel from the local test target through the attempt controller, candidate generator, worker pool, and local test auth server, and produce result/log output.
• Access state: No account required.
• Failure/recovery: If any stage of the pipeline is unavailable, the run does not silently complete; the affected stage reports the failure and the run can be restarted.
• Continuation: The operator reviews results and logs, then configures another run.
• Owner: Landing, Run Setup, Candidates, Attempt Runner, Response Analyzer, Queue Monitor, Results.

FR-2 — Accepted run inputs As a Security Lab Operator, I should be able to supply the target I control, test username(s), a locally generated test password list, and optional concurrency settings, so that the harness knows what to test.

• Provenance: explicit
• Trigger/input: The operator supplies the target they control, test username(s), a locally generated test password list, and optionally concurrency settings.
• Observable result: The run configuration reflects all supplied values, and concurrency settings are marked optional.
• Access state: No account required.
• Failure/recovery: If the target, test username(s), or locally generated test password list is missing, the run does not start and the missing input is reported.
• Continuation: The operator starts the run.
• Owner: Run Setup.

FR-3 — Candidate generation and reading As a Test Harness Maintainer, I should have a candidate generator that generates or reads candidate passwords using dictionary, rule-based, and exhaustive-combination approaches, so that the candidate set matches the experiment.

• Provenance: explicit
• Trigger/input: The operator or maintainer selects an approach — dictionary, rule-based, or exhaustive combinations — or supplies a locally generated test password list to read.
• Observable result: A candidate password set is produced or read, and the approach used is shown.
• Access state: No account required.
• Failure/recovery: If the supplied locally generated test password list cannot be read, or an approach yields no candidates, the failure is reported and the candidate count is not advanced.
• Continuation: The candidate set is handed to the worker pool.
• Owner: Candidates.

FR-4 — Attempt engine submission and recording As a Test Harness Maintainer, I should have an attempt engine that sends each candidate to a deliberately vulnerable local test authentication service and records whether the laboratory service accepts or rejects it, so that every candidate has a recorded laboratory outcome.

• Provenance: explicit
• Trigger/input: Each candidate from the candidate set is submitted to the deliberately vulnerable local test authentication service.
• Observable result: Each candidate has a recorded accept or reject outcome from the laboratory service.
• Access state: No account required.
• Failure/recovery: If the laboratory service does not respond, the attempt is recorded as an error rather than as an accept or reject.
• Continuation: Recorded outcomes feed the response analyzer and the central queue.
• Owner: Attempt Runner.

FR-5 — Response analysis from status codes and contents As a Test Harness Maintainer, I should have a response analyzer that determines success or failure from the controlled test application's response using HTTP status codes and response contents, so that verdicts are accurate rather than false-positive-prone.

• Provenance: explicit
• Trigger/input: The controlled test application's response to a submitted candidate.
• Observable result: A success or failure verdict determined from HTTP status codes and response contents, not from status codes alone.
• Access state: No account required.
• Failure/recovery: Where a status code alone would be ambiguous, the analyzer reports the ambiguity instead of asserting a verdict, avoiding a false positive.
• Continuation: The verdict is recorded against the attempt and reflected in the queue and results.
• Owner: Response Analyzer.

FR-6 — Worker pool and central queue As a Test Harness Maintainer, I should have a worker pool that processes candidates and a central queue that tracks pending, successful, and failed attempts, so that concurrency is managed and every attempt is accounted for.

• Provenance: explicit
• Trigger/input: Candidates enter the central queue; the worker pool claims them.
• Observable result: The central queue shows pending, successful, and failed attempts, and the worker pool processes candidates concurrently.
• Access state: No account required.
• Failure/recovery: If a worker fails, the affected attempt moves to the failed band and the error count increments while the remaining pending candidates continue.
• Continuation: The queue drains to zero pending and the final distribution is available in Results.
• Owner: Queue Monitor.

FR-7 — Results reporting As a Security Lab Operator, I should see attempts/second, number tested, the successful laboratory credential, error counts, and runtime/logs, so that I can judge how weak the lab credentials are.

• Provenance: explicit
• Trigger/input: A run completes or is in progress.
• Observable result: Attempts/second, number tested, the successful laboratory credential, error counts, and runtime/logs are reported.
• Access state: No account required.
• Failure/recovery: If no candidate was accepted, the successful laboratory credential line reports that no laboratory credential was accepted, and error counts and logs remain available.
• Continuation: The operator reviews the figures and configures another run.
• Owner: Results.

FR-8 — Operator-supplied controlled target and vulnerable local service As a Security Lab Operator, I should provide a target I control and a deliberately vulnerable local test authentication service, so that the harness has a laboratory boundary to measure against.

• Provenance: required_inference
• Trigger/input: The operator supplies the target they control and stands up the deliberately vulnerable local test authentication service.
• Observable result: The harness points at the operator-supplied target and laboratory service for the run.
• Access state: No account required.
• Failure/recovery: If the target is not reachable as a controlled local test target, the run does not start and the failure is reported.
• Continuation: The operator corrects the target and starts the run.
• Owner: Run Setup.

FR-9 — Test usernames and locally generated test password list before execution As a Security Lab Operator, I should supply test usernames and a locally generated test password list before execution, so that the harness has laboratory credentials to test.

• Provenance: required_inference
• Trigger/input: The operator supplies test username(s) and a locally generated test password list.
• Observable result: The run has the usernames and the locally generated test password list it will test.
• Access state: No account required.
• Failure/recovery: If either is missing, the run does not start and the missing input is reported.
• Continuation: The operator supplies the missing input and starts the run.
• Owner: Run Setup, Candidates.

FR-10 — Retained run state and attempt results As a Test Harness Maintainer, I should have run state and attempt results retained, so that queue processing and later result review are supported.

• Provenance: required_inference
• Trigger/input: A run is configured and executed.
• Observable result: Run state and attempt results persist across queue processing and are available for later result review.
• Access state: No account required.
• Failure/recovery: If retained state is unavailable, the run reports the failure rather than presenting incomplete results.
• Continuation: The operator or maintainer reviews retained results.
• Owner: Queue Monitor, Results.

4. User Personas

Security Lab Operator

Product context. The Security Lab Operator runs credential-strength experiments against a deliberately vulnerable local test authentication service they control. They work on their own bench, against their own laboratory service, and they want to know how weak a set of lab credentials is. They are technical, hands-on, and slightly adversarial in spirit.

Primary goal. Judge how weak the laboratory credentials are by running the harness and reading the resulting figures.

Distinct accepted responsibilities. The operator supplies the target they control, test username(s), a locally generated test password list, and optional concurrency settings. They start the run. They review attempts/second, number tested, the successful laboratory credential, error counts, and runtime/logs. They also supply the deliberately vulnerable local test authentication service that the harness measures against.

Relevant inputs or decisions. Which target they control to point at. Which test usernames to test. Which locally generated test password list to use. Whether to supply concurrency settings at all, since they are optional. Whether the reported successful laboratory credential is plausible given the list they supplied.

Interactions with other accepted participants. The operator hands the harness internals to the Test Harness Maintainer: the maintainer owns the candidate generator, attempt engine, response analyzer, worker pool, and central queue that the operator's run depends on. The operator's run is only as accurate as the maintainer's analyzer logic, and the operator is the one who sees the resulting verdicts.

Observable success. The Results surface reports attempts/second, number tested, the successful laboratory credential, error counts, and runtime/logs for the run, and the operator can judge the weakness of the lab credentials from those figures.

Test Harness Maintainer

Product context. The Test Harness Maintainer owns the harness internals: the candidate generator (dictionary, rule-based, exhaustive combinations), the attempt engine that submits each candidate to the local test auth service, the response analyzer that decides accept/reject from the controlled test application's response, and the worker pool plus central queue tracking pending, successful, and failed attempts. They work on the instrument itself rather than on a single experiment.

Primary goal. Keep the harness accurate — tune concurrency and analyzer logic so results reflect the laboratory service's actual behavior rather than false positives.

Distinct accepted responsibilities. Choosing and tuning the candidate generation approach across dictionary, rule-based, and exhaustive combinations. Ensuring the attempt engine records accept or reject for every candidate. Ensuring the response analyzer uses HTTP status codes and response contents rather than status codes alone, so that verdicts are not false-positive-prone. Tuning the worker pool and central queue so pending, successful, and failed attempts are tracked correctly. Ensuring run state and attempt results are retained for queue processing and later result review.

Relevant inputs or decisions. Which generation approach to use for a given experiment. How the analyzer should weigh status codes against response contents. How much concurrency the worker pool should apply. Whether an ambiguous response should be reported as ambiguous rather than asserted as a verdict.

Interactions with other accepted participants. The maintainer's internals serve the Security Lab Operator's run. The maintainer's analyzer decisions determine whether the operator's reported successful laboratory credential is trustworthy, and the maintainer's queue and worker-pool behavior determines the attempts/second and error counts the operator reads.

Observable success. The central queue correctly tracks pending, successful, and failed attempts; the response analyzer returns verdicts grounded in both status codes and response contents; and the operator's reported results are accurate rather than false-positive-prone.

5. Core User Flows

Flow 1 — Security Lab Operator runs a credential-strength experiment

1. The Security Lab Operator opens the Landing page. The oversized gauge cluster reads 0.0 attempts/sec with the amber needle at rest, and the "tested" and "accepted" bezels read 0. The engraved schematic strip shows six numbered nodes on a hairline rail, all unlit.
2. The operator reads the laboratory boundary statement: the harness measures against a target they control and a deliberately vulnerable local test authentication service, using a locally generated test password list, and is not for use against systems they do not control.
3. The operator activates the amber "Arm run" control and arrives at Run Setup.
4. On Run Setup, the operator supplies the target they control on the ruled target line. They supply test username(s). They supply the locally generated test password list. They optionally supply concurrency settings — the concurrency row is visually marked optional, and the run is valid without it.
5. If the target, test username(s), or locally generated test password list is missing, the corresponding ruled row shows a muted steel inline message and the start control stays disabled. The operator corrects the offending row; the message clears and the start control re-enables.
6. The operator starts the run. The harness moves to Candidates.
7. On Candidates, the operator selects a generation approach — dictionary, rule-based, or exhaustive combinations — or reads the supplied locally generated test password list. The candidate count renders as an oversized tabular condensed numeral and the module status lamp lights.
8. If the supplied locally generated test password list cannot be read, or the selected approach yields no candidates, the module reports the failure in muted steel and the count holds its last known value. The operator supplies a readable list or selects a different approach, and the count repopulates.

9. The candidate set is handed to the worker pool. On Queue Monitor, the full-width strip of stacked tick marks lights in sequence as workers claim candidates, with pending, successful, and failed as three distinct bands. Queue depth reads as an oversized tabular condensed numeral.
10. On Attempt Runner, each candidate is submitted to the deliberately vulnerable local test authentication service, and the laboratory service's accept or reject outcome is recorded. Accept outcomes carry the amber instrument signal; reject outcomes render in desaturated warm grey.
11. If the deliberately vulnerable local test authentication service does not respond, the attempt is recorded as an error rather than as an accept or reject, and the error count increments. When the laboratory service responds again, submission resumes from the queue and the error count holds its accumulated value.
12. On Response Analyzer, the controlled test application's response is analyzed using HTTP status codes and response contents, not status codes alone. The verdict lands as a single amber pulse on the matched row when accepted, then holds; rejections render in desaturated warm grey.
13. If a status code alone would be ambiguous, the analyzer reports the ambiguity rather than asserting a verdict, and the attempt is not counted as accepted. Once the response contents resolve the ambiguity, the verdict is determined and displayed.
14. The queue drains to zero pending, with the successful and failed bands holding their final counts.
15. On Results, the operator reads attempts/second, number tested, the successful laboratory credential, error counts, and runtime/logs. The successful laboratory credential is called out on its own full-width amber-ruled line.
16. If no candidate was accepted, the successful laboratory credential line reads as no laboratory credential accepted, in desaturated warm grey, and the error count and logs remain available.

17. The operator judges how weak the lab credentials are from the reported figures, then configures another run by returning to Run Setup. Starting a new run replaces the readouts and logs with the new run's figures.

Flow 2 — Test Harness Maintainer tunes the harness internals

1. The Test Harness Maintainer opens Candidates to review how the candidate set for an experiment is produced. They choose between dictionary, rule-based, and exhaustive-combination approaches, or point the generator at a supplied locally generated test password list to read.
2. The maintainer confirms the candidate count and the approach used. If an approach yields no candidates, they see the failure reported in muted steel and select a different approach.
3. The maintainer opens Attempt Runner and confirms that each candidate is submitted to the deliberately vulnerable local test authentication service and that an accept or reject outcome is recorded for every candidate. They confirm that a non-responding laboratory service produces an error record rather than a false accept or reject.
4. The maintainer opens Response Analyzer and inspects the HTTP status code and response contents behind a verdict. They adjust the analyzer logic so that success or failure is determined from both status codes and response contents rather than status codes alone, keeping verdicts accurate rather than false-positive-prone.
5. Where a status code alone would be ambiguous, the maintainer confirms the analyzer reports the ambiguity instead of asserting a verdict, and that the attempt is not counted as accepted until the response contents resolve it.
6. The maintainer opens Queue Monitor and confirms that the worker pool processes candidates and that the central queue tracks pending, successful, and failed attempts as three distinct bands. They tune concurrency so the queue drains correctly.
7. If a worker fails, the maintainer confirms the affected attempt moves to the failed band and the error count increments while the remaining pending candidates continue processing.

8. The maintainer confirms that run state and attempt results are retained, so that queue processing and later result review are supported.
9. The maintainer opens Results and confirms that attempts/second, number tested, the successful laboratory credential, error counts, and runtime/logs reflect the tuned behavior, and that the successful laboratory credential is called out on its own full-width amber-ruled line.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. Muse: MARQ by Garmin — luxury instrument aesthetic. Headline: Precision instrumentation for the lab bench — titanium dark, dial data, one amber signal.

Color tokens (dark mode).

Proportion: ~80% graphite/titanium, ~15% champagne structure, ~5% amber signal. The amber accent must stay scarce so it reads as an instrument light, not decoration.

Typography.

• Headings: Saira Condensed — condensed technical display at heavy weights for numerals and short instrument labels. Uppercase, wide tracking on micro-labels (attempts/sec, queue depth); tight tracking on large readouts. Numerals are the headline: tabular, condensed, oversized. Condensed is for data and titles only.
• Body: Saira at comfortable size.
• Scale: 1.25 modular on a 4pt baseline — 12 / 14 / 18 / 24 / 32 / 48 / 72 / clamp(44px, 9vw, 128px) for the hero readout.
• Micro-labels: 11px uppercase Saira Condensed, tracked +0.14em.
• Body: 16px / 1.6.
• Data rows: 14px tabular.

Shape language. Circular gauges and bezels are the primary geometry — every rate, count, and queue state can be expressed as a dial, an arc, or a ring. Rounded-rectangle panels with 2px radii and hairline 1px borders for everything else. Ruled data rows with a 1px baseline under each entry, like an engraved spec sheet. No pill buttons, no large radii, no blobs. Corners are sharp-ish and machined.

Layout. Dark, edge-to-edge instrument panel. Left rail is a vertical run-status spine (target, username, mode, concurrency) that stays fixed while the right column scrolls through the pipeline: Input → Candidate Generator → Worker Pool → Local Test Auth Server → Response Analyzer → Result/Log. Each pipeline stage is a numbered instrument module with a ruled header, a status lamp, and a data readout. Queue Monitor is a full-width horizontal strip of stacked tick marks showing pending / successful / failed as three coloured bands. Results sit at the bottom as a spec-sheet table, not cards.

Imagery. No photography of people. Imagery is the instrument itself: circular gauge clusters, topographic contour lines as faint background texture, engraved technical diagrams of the request pipeline, and macro textures of brushed titanium and sapphire glass used as panel backgrounds at very low opacity. The pipeline diagram from the brief is redrawn as an engraved schematic with numbered nodes and thin luminous strokes.

Avoid. Blue/indigo status colours on white; generic dashboard card grid with hover-lift shadows; pill buttons and large soft radii; red/green traffic-light status chips (rejections stay in desaturated warm grey); photography of people, stock team imagery, or any human-centred illustration; gradient-blob or glassmorphism hero treatments; playful, bouncy, or springy easing; making the amber accent common. The generic indigo/blue-on-white SaaS template is forbidden for this project.

7. Signature Design Concept

The public entry is an instrument face, not a marketing hero.

Full-bleed dark graphite ground (#0E1012). The dominant element is an oversized circular gauge cluster occupying the right two-thirds of the viewport: a large central dial reading attempts/second with the amber needle live, flanked by two smaller bezels for tested and accepted. The bezels and gauge arcs are champagne (#C8A96A); the needle and the accept signal are amber (#E8A33D); labels and units are muted steel (#7C8189).

The left third holds the product name in condensed uppercase at clamp(44px, 9vw, 128px), stacked over a ruled target line, with a single amber "Arm run" control pinned beneath it. Behind the gauges, faint topographic contour lines and a very low-opacity brushed-titanium texture.

Beneath the gauge cluster, the pipeline is rendered as an engraved schematic strip — six numbered nodes on a hairline rail with a travelling amber pulse that marks which stage is currently executing. The six nodes are the accepted pipeline: Input, Candidate Generator, Worker Pool, Local Test Auth Server, Response Analyzer, Result/Log.

There is no centred headline, no subtext block, no blue button, and no gradient blob. The composition is an instrument face. Every readable element — the product name, the ruled target line, the micro-labels, the numerals, and the "Arm run" control — stays whole inside the viewport and its container at 375px, 768px, and 1280px, wrapping or scaling to fit, with no other element covering any part of it.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: dimensional_css

Landing Hero Motion Brief

• Focal subject. The oversized circular gauge cluster: a central attempts/second dial with the amber needle, flanked by the "tested" and "accepted" bezels, over faint topographic contour lines and a very low-opacity brushed-titanium texture.
• Input → transformation → outcome thesis. As the operator's run state becomes available, the gauge needles sweep from zero to their live values with a physical ease-out and the counters tick up digit by digit; the outcome is an instrument face reading real run state — attempts/second, tested, accepted — rather than a decorative animation.
• Motion vocabulary. Precise and mechanical, never playful. Needle sweeps with physical ease-out. Digit-by-digit counter ticks. Queue tick marks lighting in sequence as workers claim candidates. A single amber pulse landing on the matched row when the accept verdict arrives, then holding. A travelling amber pulse along the engraved schematic rail marking the currently executing stage. Slow product-turntable-style parallax on the hero gauge cluster as the page scrolls.
• Composed first frame. Gauges at rest with needles at zero, the central dial reading 0.0 attempts/sec, the "tested" and "accepted" bezels reading 0, the schematic strip showing all six nodes unlit, the product name in condensed uppercase over the ruled target line, and the amber "Arm run" control pinned beneath it.
• Reduced-motion state. With prefers-reduced-motion, needles jump to their final values, counters render statically, and tick marks appear in place. The parallax on the hero gauge cluster is removed and the cluster holds a single static composition. All readable text and controls remain whole and usable.

9. Non-Functional Requirements

NFR-1 — Laboratory boundary. Testing is limited to a local test target the operator controls and a deliberately vulnerable local test authentication service; the harness is not for use against systems the operator does not control. (Provenance: explicit. Rationale: explicit hard constraint in the authoritative user evidence.)

NFR-2 — Locally generated test password lists. Password lists are locally generated test lists. (Provenance: explicit. Rationale: explicit hard constraint in the authoritative user evidence.)

NFR-3 — Optional concurrency settings. Concurrency settings are optional; the harness must run correctly without them. (Provenance: explicit. Rationale: explicit hard constraint in the authoritative user evidence.)

NFR-4 — Verdict accuracy. The response analyzer must determine success or failure from HTTP status codes and response contents rather than status codes alone, because relying on only status codes can produce false positives. (Provenance: explicit. Rationale: stated in the authoritative user evidence.)

NFR-5 — Retained run state. Run state and attempt results must be retained to support queue processing and later result review. (Provenance: required_inference. Rationale: required to make the accepted run lifecycle executable.)

NFR-6 — Readable text and controls. Headlines, wordmarks, labels, numbers, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit, with no other element covering any part of them. (Provenance: explicit. Rationale: stated in the creative direction.)

NFR-7 — Reduced motion. All motion respects prefers-reduced-motion: needles jump to final values, counters render statically, tick marks appear in place, and a usable static arrangement is provided. (Provenance: explicit. Rationale: stated in the creative direction.)

10. Tech Stack

• Frontend: React — the instrument-panel UI (Landing, Run Setup, Candidates, Attempt Runner, Response Analyzer, Queue Monitor, Results) with the dark graphite, champagne, and amber instrument treatment.
• Backend: Python / FastAPI — the attempt controller, candidate generator, attempt engine, response analyzer, worker pool, and result/log output.
• Storage: Persistent storage for retained run state and attempt results, supporting queue processing and later result review.
• Queue/state: Redis — required for the central queue tracking pending, successful, and failed attempts and for run state.
• Deployment: Docker / docker-compose for the local laboratory harness.

11. Assumptions and Constraints

Assumptions.

• The Security Lab Operator supplies and controls the target and the deliberately vulnerable local test authentication service; the harness does not provision them. (required_inference)
• The operator supplies test username(s) and a locally generated test password list before execution. (required_inference)
• The harness runs locally on the operator's bench; no remote or third-party target is in scope. (required_inference)
• Run state and attempt results are retained so that queue processing and later result review are supported. (required_inference)

Constraints.

• Testing is limited to a local test target the operator controls and a deliberately vulnerable local test authentication service; the harness is not for use against systems the operator does not control. (explicit)
• Password lists are locally generated test lists. (explicit)
• Concurrency settings are optional. (explicit)
• The response analyzer must use HTTP status codes and response contents, not status codes alone. (explicit)
• The generic indigo/blue-on-white SaaS template is forbidden for this project. (explicit)
• Rejections render in desaturated warm grey, never a red/blue status colour. (explicit)
• The amber accent must remain scarce — reserved for the live needle, the accept verdict, and active queue states. (explicit)

12. Glossary

• Attempt — A single submission of one candidate password to the deliberately vulnerable local test authentication service.
• Attempt controller — The component that drives the pipeline from the local test target through candidate generation, the worker pool, the local test auth server, and result/log output.
• Attempt engine — The component that sends each candidate to the deliberately vulnerable local test authentication service and records whether the laboratory service accepts or rejects it.
• Attempts/second — The measured rate at which attempts are submitted during a run.
• Candidate — A password produced or read by the candidate generator for submission.
• Candidate generator — The component that generates or reads candidate passwords using dictionary, rule-based, or exhaustive-combination approaches.
• Central queue — The queue that tracks pending, successful, and failed attempts.
• Concurrency settings — Optional settings controlling how the worker pool processes candidates.
• Controlled test application — The deliberately vulnerable local test authentication service the operator controls and points the harness at.
• Dictionary approach — A candidate generation approach that draws candidates from a word list.
• Error count — The number of attempts that could not be resolved to an accept or reject outcome.
• Exhaustive combinations — A candidate generation approach that enumerates combinations of characters or tokens.
• False positive — An incorrect success verdict, which relying on only HTTP status codes can produce.

• Local test auth server — The deliberately vulnerable local test authentication service that accepts or rejects each candidate.
• Locally generated test password list — A password list generated locally for laboratory testing.
• Pending attempt — A candidate in the central queue that has not yet been claimed by a worker.
• Response analyzer — The component that determines success or failure from the controlled test application's response using HTTP status codes and response contents.
• Rule-based approach — A candidate generation approach that applies transformation rules to base words.
• Run — One configured execution of the harness against a target, with test username(s), a locally generated test password list, and optional concurrency settings.
• Runtime/logs — The elapsed runtime of a run and its log entries.
• Successful laboratory credential — The candidate password that the deliberately vulnerable local test authentication service accepted.
• Test username — A username supplied by the operator for the run.
• Worker pool — The set of workers that claim candidates from the central queue and process them concurrently.