1.1 Entry points and directory initialization SWD-001

Design intent

The VECTOR entry scripts establish runtime assumptions before analysis by validating CLI input and preparing the output filesystem layout.

Inputs

  • Source analysis path and optional application name.
  • Network protocol, target, and port.

Processing

  • VECTOR-Code creates output/databases, output/results, and output/cbom before invoking analysis steps.
  • VECTOR-Network validates required CLI or interactive inputs before scanner execution.

Outputs

  • Prepared local directories and normalized runtime arguments.

Failure handling

  • Missing paths, unreadable directories, empty targets, and invalid ports stop execution before analysis starts.

Parent links: ARC-001 VECTOR runtime context

Attribute Value
release Alpha

1.2 Source inventory pipeline sequencing SWD-002

Design intent

The VECTOR-Code workflow is implemented as a fixed pipeline from language detection to database creation, query execution, and CBOM generation.

Inputs

  • Readable project directory.
  • Optional application name.

Processing

  • detect_languages determines supported languages from cloc output.
  • create_databases deduplicates by CodeQL language and creates analysis databases.
  • run_queries generates SARIF findings.
  • generate_cbom converts SARIF results into CBOM files.

Outputs

  • Per-language SARIF artifacts and CBOM artifacts.

Failure handling

  • Empty language sets, failed database creation, missing SARIF results, and conversion failures terminate the pipeline with explicit errors or warnings.

Parent links: ARC-002 VECTOR-Code processing component

Attribute Value
release Alpha

1.3 Inventory artifact segregation by analysis surface SWD-003

Design intent

Source-code inventory artifacts and network-scan inventory artifacts are kept in separate raw and derived files while sharing a common inventory objective.

Inputs

  • Source SARIF files.
  • Raw TLS and SSH scan JSON files.

Processing

  • VECTOR-Code stores databases, SARIF, and derived CBOM files under dedicated output subdirectories.
  • VECTOR-Network stores per-target raw scan files and emits protocol-specific CBOM JSON files.

Outputs

  • Distinct raw and derived artifacts for each analysis surface.

Failure handling

  • Conversion is not attempted when the expected raw or intermediate artifact is absent.

Parent links: ARC-003 Unified inventory coverage boundary

Attribute Value
release Alpha

1.4 External command invocation contracts SWD-004

Design intent

VECTOR wraps required third-party tools through direct subprocess calls with explicit command-line parameters.

Inputs

  • Tool-specific paths, project roots, scanner targets, and result file names.

Processing

  • cloc is invoked with JSON output enabled.
  • CodeQL database creation and query analysis are executed through the CodeQL CLI.
  • cryptobom converts SARIF files into CBOM artifacts.
  • testssl.sh and zgrab2 generate raw network results.

Outputs

  • Tool-specific stdout, stderr, and result files used by later steps.

Failure handling

  • Missing binaries or non-zero subprocess outcomes are surfaced as runtime errors or explicit workflow failures.

Parent links: ARC-004 External analysis tool adapters

Attribute Value
release Alpha

1.5 TLS scan lifecycle and parser handoff SWD-005

Design intent

The TLS workflow produces a raw testssl JSON file and then parses it into structured data for CBOM generation.

Inputs

  • Target host or address.
  • Target port.
  • Local path to testssl.sh.

Processing

  • Existing conflicting output files are removed before a new scan begins.
  • testssl.sh writes its raw JSON output to a predictable file path.
  • The converter reads the JSON file, parses versions, cipher suites, groups, certificates, and target data, and constructs the final CBOM object.

Outputs

  • Raw TLS scan JSON and <target>_tls_cbom.json.

Failure handling

  • Missing testssl.sh, missing output files, empty output files, and timeout conditions terminate the TLS workflow.

Parent links: ARC-005 TLS assessment workflow

Attribute Value
release Alpha

1.6 SSH scan lifecycle and parser handoff SWD-006

Design intent

The SSH workflow produces a raw zgrab2 JSON file and then parses it into structured data for CBOM generation.

Inputs

  • Target host or address.
  • Target port.
  • Local availability of zgrab2.

Processing

  • zgrab2 writes a raw SSH scan file for the target.
  • The SSH converter reads the JSON file, validates the expected structure, extracts the SSH banner and algorithm lists, and builds the final CBOM object.

Outputs

  • Raw SSH scan JSON and <domain>_ssh_cbom.json.

Failure handling

  • Missing zgrab2, missing output files, empty output files, and malformed scan structures terminate the SSH workflow.

Parent links: ARC-006 SSH assessment workflow

Attribute Value
release Alpha

1.7 CBOM generation routines SWD-007

Design intent

VECTOR uses separate conversion routines for source-analysis findings and network-analysis findings while converging on JSON CBOM outputs.

Inputs

  • Source SARIF files.
  • Parsed TLS scan data.
  • Parsed SSH scan data.

Processing

  • VECTOR-Code invokes cryptobom generate for each SARIF file.
  • TLS and SSH converters assemble CBOM document structures directly in Python and serialize them to JSON.

Outputs

  • Generated CBOM JSON files for source, TLS, and SSH workflows.

Failure handling

  • CBOM generation failures are reported and the failed artifact is not added to the set of successful outputs.

Parent links: ARC-007 CBOM generation and storage

Attribute Value
release Alpha

1.8 Defensive validation and failure boundaries SWD-008

Design intent

Validation logic constrains execution to locally safe operations and prevents conversion from proceeding on invalid or incomplete data.

Inputs

  • User-provided paths, targets, ports, and generated result files.

Processing

  • Ports are constrained to the valid TCP range.
  • Empty targets are rejected.
  • Result files are checked for existence and non-zero size before conversion.
  • Timeouts constrain long-running TLS scans.

Outputs

  • Explicit error messages and terminated workflows when a safety boundary is crossed.

Failure handling

  • No downstream conversion or success reporting occurs after a validation or timeout failure.

Parent links: ARC-008 Non-invasive network trust boundary

Attribute Value
release Alpha

1.9 Algorithm decomposition and modeling SWD-009

Design intent

The network converters decompose protocol findings into explicit cryptographic components so inventory artifacts expose the underlying mechanisms rather than only opaque suite names.

Inputs

  • TLS cipher-suite names, curve names, and related protocol metadata.
  • SSH key exchange, cipher, MAC, and host-key algorithm identifiers.

Processing

  • TLS conversion maps suites into key exchange, authentication, encryption, and hash elements.
  • Hybrid curve names are decomposed into elliptic-curve and post-quantum components where mapping data exists.
  • SSH conversion maps algorithm identifiers through CSV-backed lookup tables into CBOM algorithm properties.

Outputs

  • Component-level algorithm records in generated CBOM artifacts.

Failure handling

  • Unknown algorithms fall back to default category metadata rather than crashing the converter.

Parent links: ARC-009 Algorithm modeling layer

Attribute Value
release Alpha

1.10 JSON interface and naming conventions SWD-010

Design intent

VECTOR's external interface is primarily file-based, with JSON used for raw scanner outputs and generated CBOM artifacts.

Inputs

  • Raw tool outputs and intermediate findings already represented as JSON or SARIF.

Processing

  • File names are derived from the target or intermediate artifact stem.
  • JSON serialization is performed with explicit encoding and formatting choices in each workflow.

Outputs

  • Stable, inspectable artifact names such as crypto-python.sarif, <target>_tls_cbom.json, and <domain>_ssh_cbom.json.

Failure handling

  • The workflow reports serialization or file-write failures rather than hiding them behind silent success.

Parent links: ARC-010 Open artifact interfaces

Attribute Value
release Alpha

1.11 VECTOR-Score module decomposition and internal design SWD-011

Design intent

VECTOR-Score decomposes into four Python modules and one data file, each with a single responsibility.

File structure

tor/VECTOR-Score/
├── __init__.py
├── main.py                          # CLI entry point
├── algorithm_classifier.py          # Classification logic
├── cbom_scorer.py                   # CBOM annotation engine
├── report_generator.py              # Markdown report builder
└── data/
    └── algorithm-risk-catalog.yaml  # Classification catalog

Module responsibilities

algorithm_classifier.py

  • Loads data/algorithm-risk-catalog.yaml at module import time.
  • Exposes a classify(name, primitive, param_set_identifier) function returning a RiskClassification dataclass.
  • Matching order: (1) exact name match, (2) regex pattern match on name, (3) primitive-type fallback, (4) unknown.
  • Key-size-aware classification: uses param_set_identifier (the CBOM parameterSetIdentifier field) to distinguish AES-128 from AES-256, etc.

cbom_scorer.py

  • Exposes score_cbom(cbom: dict) -> dict as a pure function returning an annotated deep copy.
  • Iterates the components array; for each component where cryptoProperties.assetType == "algorithm", calls classify() and appends pqcmat:-namespaced entries to the component's properties array.
  • Properties added per component: pqcmat:risk-classification, pqcmat:risk-score, pqcmat:rationale, pqcmat:recommended-migration, pqcmat:reference.
  • Adds pqcmat:scored-at to metadata.properties.
  • Compatible with both type: "crypto-asset" (VECTOR-Code output) and type: "cryptographic-asset" (VECTOR-Network output).

report_generator.py

  • Exposes generate_report(scored_cbom: dict) -> str returning a Markdown string.
  • Sections: title and metadata header, summary count table by classification, per-classification finding tables (name, primitive, key size, rationale, migration target), normative references.

main.py

  • CLI: python3 main.py <cbom.json> [--output <path>] [--report <path>] [--no-report]
  • Default output paths: <input-stem>_scored.json and <input-stem>_risk_report.md alongside the input file.
  • Validates that the input path exists and is parseable as JSON before invoking the scorer.

Inputs

  • Any CycloneDX CBOM JSON file (VECTOR-Code or VECTOR-Network output).

Outputs

  • <stem>_scored.json: the input CBOM with pqcmat: risk properties added to each algorithm component.
  • <stem>_risk_report.md: a Markdown summary grouped by risk classification.

Failure handling

  • Non-existent input path: exit with explicit error before processing.
  • Unparseable JSON: exit with explicit error before processing.
  • Algorithm not in catalog: assign unknown classification; do not raise an exception.

Parent links: ARC-011 VECTOR-Score: standalone quantum risk scoring module

Attribute Value
release Alpha