1 TOR SRSs SRS-TOR

System-level requirements for the TOR subsystem.

1.1 Persist output artifacts in predictable locations SRS-001

VECTOR SHALL write generated source-analysis and network-analysis artifacts to predictable output files and directories under the local workspace.

Rationale

The current implementation writes databases, SARIF results, raw scan results, and CBOM files to the filesystem for later inspection and reuse.

Acceptance criteria

• VECTOR-Code creates and uses dedicated output directories for databases, results, and CBOM files.
• VECTOR-Network writes raw scan files and generated CBOM files to named local JSON files.
• Output paths remain inspectable after process completion.

Parent links: MRS-010 Produce open, reusable output artifacts

Child links: TCS-001 Verify persisted output locations for VECTOR-Code artifacts

Attribute	Value
release	Alpha
type	F
importance	4
urgency	4
vm	T

1.2 Detect supported source languages from the target project SRS-002

VECTOR-Code SHALL run a language-detection step against the supplied project path and SHALL continue only when at least one supported language is detected above the configured threshold.

Rationale

The implemented source-analysis pipeline depends on a supported-language set before CodeQL databases can be created.

Acceptance criteria

• The input path is checked for existence, directory type, and read permission before analysis starts.
• Language detection is derived from cloc --json output.
• The current supported languages are Python, C, and C++.

Parent links: MRS-004 Support source-code analysis for current target languages

Child links: TCS-002 Verify supported language detection

Attribute	Value
release	Alpha
type	F
importance	5
urgency	4
vm	T

1.3 Create CodeQL databases through the external CLI SRS-003

VECTOR-Code SHALL invoke the external CodeQL CLI to create one analysis database per detected CodeQL language.

Rationale

The current implementation uses external CodeQL tooling to prepare the source tree for cryptographic inventory queries.

Acceptance criteria

• Duplicate source languages that map to the same CodeQL language do not create redundant databases.
• Database creation uses --build-mode=none.
• Failed database creation for one language does not fabricate a successful result for that language.

Parent links: MRS-008 Orchestrate open-source analysis tooling

Child links: TCS-003 Verify CodeQL database creation

Attribute	Value
release	Alpha
type	F
importance	4
urgency	4
vm	T

1.4 Run cryptographic inventory queries on created databases SRS-004

VECTOR-Code SHALL run cryptographic inventory queries against each created CodeQL database and SHALL collect the resulting SARIF artifacts.

Rationale

Source-code inventory requires a query phase that transforms prepared databases into inspectable findings.

Acceptance criteria

• Each created CodeQL database is checked against a configured query path for its CodeQL language.
• Successful query execution produces a SARIF output file for that language.
• Missing query paths or failed query execution do not silently report successful findings.

Parent links: MRS-001 Inventory cryptography across code and network surfaces

Child links: TCS-004 Verify SARIF generation from CodeQL queries

Attribute	Value
release	Alpha
type	F
importance	5
urgency	5
vm	T

1.5 Convert source-analysis findings into CBOM artifacts SRS-005

VECTOR-Code SHALL convert generated SARIF files into CBOM JSON artifacts using the configured application name.

Rationale

The implemented pipeline currently ends with SARIF-to-CBOM conversion, which makes the inventory consumable by downstream tooling.

Acceptance criteria

• Every valid SARIF file is eligible for CBOM generation.
• Failed conversion for one SARIF file does not report that file as a generated CBOM artifact.
• Generated CBOM files are named from the SARIF artifact stem.

Parent links: MRS-003 Produce standardized CBOM artifacts

Child links: TCS-005 Verify SARIF-to-CBOM conversion

Attribute	Value
release	Alpha
type	F
importance	5
urgency	4
vm	T

1.6 Scan TLS-enabled services by target and port SRS-006

VECTOR-Network SHALL accept a target and port for TLS assessment and SHALL invoke the configured TLS scanner to produce a raw JSON result file.

Rationale

The implemented TLS workflow is target-and-port driven and depends on persisted raw output before conversion.

Acceptance criteria

• TLS assessment validates that the target is non-empty and the port is within the supported range.
• Existing conflicting output files are removed before a new TLS scan starts.
• A successful scan produces a non-empty JSON result file.

Parent links: MRS-005 Support TLS service assessment

Child links: TCS-006 Verify raw TLS scan output generation

Attribute	Value
release	Alpha
type	F
importance	5
urgency	4
vm	T

1.7 Model TLS findings with classical, hybrid, and PQ-aware decomposition SRS-007

VECTOR-Network SHALL convert TLS scan results into a CBOM representation that preserves decomposed cryptographic algorithms, including supported hybrid or post-quantum-related entries.

Rationale

The implemented TLS conversion logic decomposes cipher suites, curves, and hybrid constructions into explicit inventory components.

Acceptance criteria

• TLS conversion reads structured JSON scan input and produces a CBOM JSON document.
• Cipher-suite decomposition captures key exchange, authentication, encryption, and hashing elements when present.
• Hybrid or PQ-related curve identifiers are represented when they are present in the mapped input data.

Parent links: MRS-002 Recognize post-quantum and hybrid algorithms

Child links: TCS-007 Verify TLS CBOM decomposition

Attribute	Value
release	Alpha
type	F
importance	5
urgency	4
vm	T

1.8 Scan SSH-enabled services by target and port SRS-008

VECTOR-Network SHALL accept a target and port for SSH assessment and SHALL invoke the configured SSH scanner to produce a raw JSON result file.

Rationale

The implemented SSH workflow depends on a persisted scan result that is later parsed into inventory components.

Acceptance criteria

• SSH assessment validates that the target is non-empty and the port is within the supported range.
• A successful SSH scan produces a non-empty JSON result file.
• The generated raw SSH output is suitable for later CBOM conversion.

Parent links: MRS-006 Support SSH service assessment

Child links: TCS-008 Verify raw SSH scan output generation

Attribute	Value
release	Alpha
type	F
importance	5
urgency	4
vm	T

1.9 Provide a ready-to-use Linux execution environment SRS-009

VECTOR SHALL rely on a Linux workspace that provides access to its expected local tool paths and writable output locations for both source-analysis and network-analysis workflows.

Rationale

The current implementation hard-codes several command-line tools and output locations, making runtime assumptions part of the operational contract.

Acceptance criteria

• VECTOR-Code creates its expected output directories before analysis steps start.
• VECTOR-Network checks that required converter scripts and scanner paths exist before conversion or scan processing continues.
• Runtime assumptions are explicit enough to verify in a controlled environment.

Parent links: MRS-007 Run in a reproducible Linux-based environment

Child links: TCS-009 Verify Linux runtime assumptions and tool-path checks

Attribute	Value
release	Alpha
type	F
importance	4
urgency	4
vm	T

1.10 Fail safely for invalid inputs, missing tools, and incomplete outputs SRS-010

VECTOR SHALL stop or constrain execution safely when required inputs are invalid, mandatory tools are unavailable, or expected result files are missing or empty.

Rationale

The implemented workflows already perform defensive checks around targets, ports, filesystem state, scanner presence, and generated outputs.

Acceptance criteria

• Invalid ports and empty targets are rejected before scanner invocation.
• Missing required tools or scripts terminate the affected workflow with an explicit error.
• Missing or empty result files do not proceed to CBOM conversion as if analysis succeeded.

Parent links: MRS-009 Preserve non-invasive assessment behavior

Child links: TCS-010 Verify safe failure behavior

Attribute	Value
release	Alpha
type	F
importance	5
urgency	4
vm	T

1.11 Classify cryptographic algorithms in a CBOM by quantum risk SRS-011

VECTOR SHALL accept a CycloneDX CBOM JSON file as input and classify each algorithm component according to its quantum risk level, using a data-driven catalog that encodes normative guidance from NIST, BSI TR-02102, and ANSSI.

Rationale

The classification step decouples the scoring logic from the inventory tools, allowing any CBOM produced by VECTOR-Code or VECTOR-Network (or any third-party tool producing a compliant CycloneDX CBOM) to be scored. A data-driven catalog (YAML) ensures the classification rules can be updated as standards evolve without modifying source code.

Acceptance criteria

• Given a CBOM containing RSA, ECDH, or DH algorithm components, the scorer assigns the quantum-vulnerable classification to each.
• Given a CBOM containing ML-KEM or ML-DSA components, the scorer assigns the non-hybrid classification to each.
• Given a CBOM containing AES-256 or SHA-256 components, the scorer assigns the quantum-safe classification.
• Given an unrecognized algorithm name, the scorer assigns the unknown classification.
• Only components with cryptoProperties.assetType equal to algorithm are scored; protocol, certificate, and related-crypto-material components are left unmodified.

Parent links: MRS-011 Assess quantum risk of discovered cryptographic assets

Child links: TCS-011 Verify quantum risk classification

Attribute	Value
release	Alpha
type	F
importance	5
urgency	5
vm	T

1.12 Produce a CBOM annotated with quantum risk properties SRS-012

VECTOR SHALL produce an annotated copy of the input CBOM in which each scored algorithm component carries additional pqcmat:-namespaced properties recording its risk classification, risk score, rationale, recommended migration target, and normative reference.

Rationale

Embedding the risk classification directly into the CBOM document allows downstream tools and workflows to consume the scored output using standard CycloneDX tooling. The pqcmat: namespace prefix prevents collisions with other CycloneDX tool annotations. The original CBOM structure and all existing fields are preserved.

Acceptance criteria

• The annotated CBOM is valid JSON and retains all fields from the input CBOM.
• Each scored algorithm component contains a properties array entry with name: "pqcmat:risk-classification" and a non-empty value.
• Each scored algorithm component contains a properties array entry with name: "pqcmat:risk-score" with value one of high, medium, low, or none.
• Each scored algorithm component contains a properties array entry with name: "pqcmat:recommended-migration".
• The annotated CBOM metadata.properties array contains a pqcmat:scored-at entry recording the scoring timestamp.

Parent links: MRS-011 Assess quantum risk of discovered cryptographic assets

Child links: TCS-012 Verify that annotated CBOM contains 'pqcmat' risk properties

Attribute	Value
release	Alpha
type	F
importance	5
urgency	5
vm	T

1.13 Produce a Markdown risk report grouped by classification SRS-013

VECTOR SHALL produce a Markdown report summarizing the quantum-threat risk findings from a scored CBOM, grouping algorithm findings by risk classification and including a count summary table, per-finding details (algorithm name, primitive, key size, rationale, migration target), and a normative references section.

Rationale

While the annotated CBOM is the machine-readable output, security and engineering teams require a human-readable artefact that can be reviewed without CBOM tooling. Grouping findings by risk level allows reviewers to prioritize remediation efforts.

Acceptance criteria

• The report is a valid Markdown document with a header identifying the scored target and timestamp.
• The report contains a summary table with columns: risk classification and algorithm count.
• The report contains at least one section per non-empty risk classification present in the scored CBOM.
• Each per-classification section contains a table listing: algorithm name, primitive type, key size (if applicable), rationale, and recommended migration target.
• The report contains a normative references section listing all standards cited.

Parent links: MRS-011 Assess quantum risk of discovered cryptographic assets

Child links: TCS-014 Verify Markdown risk report structure and source locations

Attribute	Value
release	Alpha
type	F
importance	4
urgency	4
vm	T

1.14 Produce a single unified CBOM for multi-language projects SRS-014

VECTOR-Code SHALL merge the per-language CBOM files generated during a single run into one unified CBOM artifact that represents the complete cryptographic inventory of the analyzed project, regardless of how many programming languages were detected.

Rationale

To provide a centralized input for risk reporting (VECTOR-Score) and a single information source for downstream consumers — CBOMkit and manual reviewers – to obtain a complete picture of the project's cryptographic posture when a project contains multiple supported languages (e.g., Python and C++).

The per-language SARIF files and CodeQL databases are retained as intermediate artifacts for traceability.

Acceptance criteria

• A single CBOM file with suffix -cbom.json is written to the output/cbom/ directory at the end of every VECTOR-Code run, regardless of the number of languages detected.
• The unified CBOM contains all algorithm, certificate, related-crypto-material, and protocol components from every per-language CBOM produced during the same run.
• Each component in the unified CBOM retains its evidence.occurrences entries, including the source file path and line number from the original per-language CBOM.
• When only one language is detected, the unified CBOM is produced in the same way; behaviour is identical to the current single-language output.
• Individual per-language CBOM files (e.g., crypto-python-cbom.json) are no longer written as final output; the unified file is the sole CBOM artifact.

Parent links: MRS-003 Produce standardized CBOM artifacts

Child links: TCS-013 Verify creation of unified CBOM

Attribute	Value
release	Alpha
type	Functional (F)
importance	3
urgency	2
vm	T

1.15 Show source locations of VECTOR-Code output in risk report SRS-015

For every cryptographic algorithm identified during a vector code scan, VECTOR-Score SHALL include the file path and line number of the source where it was found, in the Markdown risk report.

Rationale

Displaying the exact file path and line number of each cryptographic API call in the risk report provides developers with a convenient and readable index and allows them to navigate directly to the code lines without having to search in the raw CBOM file. This information is already recorded in the evidence.occurrences entries of the CBOM file generated by VECTOR-Code.

Acceptance criteria

• For each algorithm in the CBOM file that has at least one evidence.occurrences entry, the risk report table row includes the source file path and the first associated line number.
• When multiple evidence.occurrences entries exist for a single component, all distinct file-path/line-number pairs are listed.
• For algorithm findings that have no evidence.occurrences (e.g., from VECTOR-Network CBOMs), the location column is left blank or marked as not applicable; no error is raised.

Parent links: MRS-011 Assess quantum risk of discovered cryptographic assets

Child links: TCS-014 Verify Markdown risk report structure and source locations

Attribute	Value
release	Alpha
type	Functional (F)
importance	4
urgency	3
vm	T

1.16 Accept a GitHub repository URL as a source analysis target SRS-016

VECTOR-Code SHALL accept a GitHub repository URL in place of a local directory path, clone the repository into a temporary workspace inside the container, and proceed with the standard source-analysis pipeline against the cloned content.

Rationale

Analysts frequently work from public or internally hosted GitHub repositories without maintaining a local checkout. Requiring a manual git clone before running VECTOR-Code adds friction. Supporting a URL directly makes the workflow consistent with how repository-level scanning is done in other security tooling and reduces setup steps for ad-hoc assessments.

Acceptance criteria

• vector code accepts a https://github.com/<owner>/<repo> URL as the path argument in addition to local filesystem paths.
• When a GitHub URL is supplied, the tool clones the repository into a temporary directory before analysis and removes it after the pipeline completes.
• The --name argument, if omitted, defaults to the repository name extracted from the URL (e.g., cryptography from https://github.com/pyca/cryptography).
• Clone failures (network error, repository not found, authentication required) terminate the run with an explicit error message and exit code 1; no partial output is written.
• The standard language-detection, CodeQL database creation, query execution, and CBOM generation steps run unchanged against the cloned content.
• Private repositories that require authentication are out of scope for this requirement; an attempt to clone such a repository results in an explicit authentication-failure error rather than silent failure.

Parent links: MRS-004 Support source-code analysis for current target languages

Attribute	Value
release	Alpha
type	Functional (F)
importance	3
urgency	3
vm	T

1.17 Provide a web-based interface for running scans and visualizing results SRS-017

VECTOR SHALL expose a web-based user interface that allows non-technical users to submit source-code analysis and network scan requests, monitor their progress, and review risk findings without using the CLI.

Rationale

The current CLI-only interaction model requires familiarity with the Dev Container environment, command-line arguments, and raw JSON or Markdown output. A web interface lowers the barrier to adoption.

Acceptance criteria

Deployment and access

• The web interface is served from within the VECTOR container and is accessible from the host browser at a documented local port without additional configuration.
• The interface does not require user authentication for the initial release; single-user local deployment is assumed.

Navigation structure

The interface is organized into four top-level sections reachable from a persistent navigation bar:

Section	Purpose
New scan	Submit a VECTOR-Code or VECTOR-Network scan
Scan history	List of all past and in-progress scans with status
Results	Risk report and CBOM viewer for a selected scan

Scan submission — VECTOR-Code

The New scan page presents a VECTOR-Code form with the following fields:

Field	Type	Required	Notes
Source	File/text input	Yes	Accepts a local filesystem path (e.g. /mnt/host-home/myproject) or a https://github.com/ URL (per SRS-016)
Application name	Text input	No	Passed as --name; defaults to the repository name when a GitHub URL is entered

Scan submission — VECTOR-Network

The New scan page also presents a VECTOR-Network form with the following fields:

Field	Type	Required	Notes
Protocol	Dropdown	Yes	Options: TLS, SSH
Target	Text input	Yes	Domain name or IP address
Port	Number input	Yes	Pre-filled with 443 when TLS is selected, 22 when SSH is selected; editable

On submission, the form validates that the target is non-empty, that the port is an integer between 1 and 65535, and that the protocol is one of the two supported values before sending the request to the API.

Scan progress monitoring

• After submission, the user is navigated automatically to a scan detail page for the new job.
• The scan detail page displays the current status and refreshes without a full page reload (polling or server-sent events are acceptable).
• The elapsed time since submission is displayed and updated in real time.
• If a scan fails, the detail page displays the error message returned by the CLI and an exit code.

Scan history

The Scan history page lists all scans that have been submitted in the current session, showing:

• Scan type (Code / Network)
• Target (path, URL, or host:port)
• Application name or scan identifier
• Submission timestamp
• Status

Each row links to the scan detail page for that job. Completed rows also link directly to the Results page for that job.

Results viewer

The Results page for a completed scan presents findings in three tabs:

Risk report tab

• The Markdown risk report produced by VECTOR-Score is rendered as HTML.
• The summary classification table (counts by risk level) is shown at the top with colour-coded risk badges: red for HIGH, orange for MEDIUM, blue for LOW, green for NONE.
• Each per-classification section is collapsible; sections for quantum-vulnerable and classically-deprecated are expanded by default.
• For VECTOR-Code results, each finding row that contains source location data (detectionContext) shows the file path and line number as a non-interactive inline code label.
• The report is downloadable as a .md file via a Download report button.

CBOM explorer tab

• The annotated CBOM JSON (output of VECTOR-Score) is displayed as a structured, collapsible tree, not as raw JSON text.
• The explorer is filterable by classification value using a dropdown so the user can isolate, for example, all quantum-vulnerable components.
• Each algorithm component node shows: variant name, primitive type, key size (if present), mode (if present), risk classification badge.
• The full annotated CBOM JSON is downloadable via a Download CBOM button.

Raw scan output tab

• For VECTOR-Network scans, the raw scanner output file (_tls_scan.json or _ssh_scan.json) is displayed as collapsible JSON and is downloadable.
• For VECTOR-Code scans, the CBOM results file is displayed as collapsible JSON and is downloadable.

General UI requirements

• All user-facing error messages state what went wrong and what the user can do next; raw stack traces are not shown in the interface (they are written to a server log only).
• The interface remains responsive during long-running scans; submitting a new scan while one is in progress is permitted.

Parent links: MRS-012 Provide a browser-accessible interface

Attribute	Value
release	Alpha
type	Functional (F)
importance	3
urgency	4
vm	T

1.18 Support standalone container deployment SRS-018

VECTOR SHALL be deployable as a standalone Docker container that can be invoked from the command line or from a CI/CD pipeline without requiring VS Code or the Dev Containers extension.

Rationale

The current deployment model is tightly coupled to VS Code Dev Containers, which requires an interactive development environment on the analyst's machine. Embedding VECTOR into automated pipelines (GitLab CI, GitHub Actions, Jenkins) is not possible under this model because pipeline runners do not run VS Code. A standalone container image that exposes the vector CLI as its entry point enables automated, unattended scanning as part of a repository's security workflow.

Acceptance criteria

• A Docker image is buildable from the project repository without the VS Code Dev Containers extension or any VS Code-specific configuration.
• The image entry point is the vector CLI; standard docker run invocations (e.g., docker run --rm vector-image vector code /src --name my-app) execute without additional setup.
• Source code to be analyzed can be mounted into the container via a Docker volume (e.g., -v $(pwd):/src) without requiring file copies into the image at build time.
• Output artifacts are written to a mountable output directory so that results are accessible on the host after the container exits.

Parent links: MRS-007 Run in a reproducible Linux-based environment

Attribute	Value
release	Alpha
type	Functional (F)
importance	3
urgency	2
vm	T