Module: vvaharness (root)
Role. The front door of VVAH: the command-line interface, the shared data contracts every stage speaks, and the run manifest.
Size. 6 files · ~2,655 LOC.
This is where a run begins. cli.py is the reception desk — it reads your command
(scan, remediate, validate, doctor…), loads your credentials from .env, checks your
Python version, finds the right config, and hands off to the orchestrator. models.py is the
shared vocabulary: the precise shapes of every object that flows between stages (findings,
threat models, reports). manifest.py writes the run's "receipt".
Explain-it-simply. If VVAH were a company, this package is the reception desk plus the official dictionary everyone must use.
Data-flow (this module)
Technical details
cli.py defines the sub-commands (_scan via orchestrator, _remediate, _validate,
_doctor, _estimate, _gc, _setup, _install_agents), .env loading (_load_dotenv),
the Python floor check (_check_python), and config resolution (_config_path_from).
__main__.py makes the package runnable as python -m vvaharness. models.py is the Pydantic
contract layer (see LLD §1). manifest.py captures a scrubbed argv, git SHA,
config SHA-256, and model roles into run_manifest.json. agentdoc.py holds the packaged
AI-agent operating instructions dropped by setup --install-agents.
File map (quick scan)
| File | LOC | Purpose |
|---|---|---|
__init__.py |
24 | vvaharness — agentic SAST pipeline. |
__main__.py |
19 | — |
agentdoc.py |
85 | Packaged AI-agent operating instructions. |
cli.py |
499 | vvaharness CLI entry point — scan, doctor, estimate. |
manifest.py |
179 | Run-level scan manifest (vvaharness). |
models.py |
1849 | Data contracts passed between pipeline steps. |
Files & functions, explained
Every class and function below has a one-line plain-English note — readable whether you write code or not. _name marks an internal helper.
__init__.py
24 LOC. vvaharness — agentic SAST pipeline.
No top-level classes or functions (package init / constants).
__main__.py
19 LOC. Utility / support module.
No top-level classes or functions (package init / constants).
agentdoc.py
85 LOC. Packaged AI-agent operating instructions.
Functions
- gemini_doc() — Provides the “gemini doc” logic.
cli.py
499 LOC. vvaharness CLI entry point — scan, doctor, estimate.
Functions
- _doctor() — (internal helper) Provides the “doctor” logic.
- _estimate() — (internal helper) Provides the “estimate” logic.
- _gc() — (internal helper) A small support routine (_gc) used within this file.
- _validate() — (internal helper) checks / decides the fix-check value.
- _remediate() — (internal helper) runs the fix value.
- _config_path_from() — (internal helper) Provides the “config path from” logic.
- _check_python() — (internal helper) checks / decides the python value.
- _repo_from() — (internal helper) Provides the “code repository from” logic.
- _load_dotenv() — (internal helper) looks up / reads the dotenv value.
- _install_agents() — (internal helper) Provides the “install agents” logic.
- _setup() — (internal helper) sets up / maintains the setup value.
- _prompt_for_remediation_inputs() — (internal helper) Provides the “prompt for fix inputs” logic.
- _print_help() — (internal helper) Provides the “print help” logic.
- main() — Runs the main value.
manifest.py
179 LOC. Run-level scan manifest (vvaharness).
Functions
- _scrub_argv() — (internal helper) hides sensitive data in the argv value.
- _git_sha() — (internal helper) Provides the “version control content hash” logic.
- _models() — (internal helper) Provides the “models” logic.
- _config_sha256() — (internal helper) Provides the “config sha256” logic.
- capture() — Checks / decides the capture value.
models.py
1849 LOC. Data contracts passed between pipeline steps.
Classes
- CVE — Represents the “known vulnerability” data/behaviour used in this file.
- Control — Represents the “Control” data/behaviour used in this file.
- _v_kind() — (internal helper) Provides the “v kind” logic.
- AppProfile — Represents the “AppProfile” data/behaviour used in this file.
- to_prompt_block() — Provides the “to prompt block” logic.
- Asset — Represents the “Asset” data/behaviour used in this file.
- _v_sensitivity() — (internal helper) Provides the “v sensitivity” logic.
- TrustBoundary — Represents the “TrustBoundary” data/behaviour used in this file.
- Threat — Represents the “attack scenario” data/behaviour used in this file.
- _v_actor() — (internal helper) Provides the “v actor” logic.
- _v_impact() — (internal helper) Provides the “v blast radius” logic.
- _v_likelihood() — (internal helper) Provides the “v likelihood” logic.
- ThreatModel — Represents the “ThreatModel” data/behaviour used in this file.
- to_prompt_block() — Provides the “to prompt block” logic.
- to_compact_prompt_block() — Provides the “to compact prompt block” logic.
- EntryPoint — Represents the “EntryPoint” data/behaviour used in this file.
- _v_kind() — (internal helper) Provides the “v kind” logic.
- Sink — Represents the “dangerous operation” data/behaviour used in this file.
- _v_line() — (internal helper) Provides the “v line” logic.
- ModuleInfo — Represents the “ModuleInfo” data/behaviour used in this file.
- _v_loc() — (internal helper) Provides the “v lines of code” logic.
- TaintSymbolRef — Represents the “TaintSymbolRef” data/behaviour used in this file.
- TaintTransferEdge — Represents the “TaintTransferEdge” data/behaviour used in this file.
- _coerce_unknown_kind() — (internal helper) reads and cleans up the unknown kind step.
- TaintEvidencePath — Represents the “TaintEvidencePath” data/behaviour used in this file.
- CFGNode — Represents the “CFGNode” data/behaviour used in this file.
- CFG — Represents the “code control-flow” data/behaviour used in this file.
- ConditionTaintEdge — Represents the “ConditionTaintEdge” data/behaviour used in this file.
- _v_condition_text() — (internal helper) Provides the “v condition text” logic.
- ReflectionFact — Represents the “ReflectionFact” data/behaviour used in this file.
- _v_line() — (internal helper) Provides the “v line” logic.
- _v_call_type() — (internal helper) Provides the “v call type” logic.
- ReflectionTaintEdge — Represents the “ReflectionTaintEdge” data/behaviour used in this file.
- _v_confidence() — (internal helper) Provides the “v confidence” logic.
- FrameworkMarkerFact — Represents the “FrameworkMarkerFact” data/behaviour used in this file.
- _v_line() — (internal helper) Provides the “v line” logic.
- _v_marker_type() — (internal helper) Provides the “v marker type” logic.
- _v_framework() — (internal helper) Provides the “v web framework” logic.
- _v_confidence() — (internal helper) Provides the “v confidence” logic.
- RouteTaintFact — Represents the “RouteTaintFact” data/behaviour used in this file.
- _v_line() — (internal helper) Provides the “v line” logic.
- _v_framework() — (internal helper) Provides the “v web framework” logic.
- ResponseDataflowFact — Represents the “ResponseDataflowFact” data/behaviour used in this file.
- _v_line() — (internal helper) Provides the “v line” logic.
- _v_framework() — (internal helper) Provides the “v web framework” logic.
- _v_response_type() — (internal helper) Provides the “v response type” logic.
- FrameworkTaintEdge — Represents the “FrameworkTaintEdge” data/behaviour used in this file.
- _v_marker_type() — (internal helper) Provides the “v marker type” logic.
- _v_framework() — (internal helper) Provides the “v web framework” logic.
- _v_confidence() — (internal helper) Provides the “v confidence” logic.
- ContextPackage — Represents the “ContextPackage” data/behaviour used in this file.
- ast_context_view() — Provides the “ast context view” logic.
- to_prompt_block() — Provides the “to prompt block” logic.
- to_decompose_prompt_block() — Provides the “to decompose prompt block” logic.
- _function_sites_block() — (internal helper) Provides the “function sites block” logic.
- _call_graph_block() — (internal helper) Provides the “call code relationship map block” logic.
- _call_graph_block_full() — (internal helper) Provides the “call code relationship map block full” logic.
- _signatures_block() — (internal helper) Provides the “signatures block” logic.
- ChunkSize — Represents the “ChunkSize” data/behaviour used in this file.
- Chunk — Represents the “analysis unit” data/behaviour used in this file.
- _v_size() — (internal helper) Provides the “v size” logic.
- _v_rank() — (internal helper) Provides the “v rank” logic.
- TaskManifest — Represents the “TaskManifest” data/behaviour used in this file.
- sorted_chunks() — Provides the “sorted analysis units” logic.
- VulnClass — Represents the “VulnClass” data/behaviour used in this file.
- DupLocation — Represents the “DupLocation” data/behaviour used in this file.
- Finding — Represents the “candidate issue” data/behaviour used in this file.
- _v_confidence() — (internal helper) Provides the “v confidence” logic.
- canonical_key() — Provides the “canonical key” logic.
- Severity — Represents the “Severity” data/behaviour used in this file.
- Chain — Represents the “Chain” data/behaviour used in this file.
- RankedFinding — Represents the “RankedFinding” data/behaviour used in this file.
- DroppedFinding — Represents the “DroppedFinding” data/behaviour used in this file.
- ScopeEntry — Represents the “ScopeEntry” data/behaviour used in this file.
- ScanMetrics — Represents the “ScanMetrics” data/behaviour used in this file.
- coverage_pct() — Provides the “coverage pct” logic.
- verification_precision_pct() — Provides the “verification precision pct” logic.
- FinalReport — Represents the “FinalReport” data/behaviour used in this file.
- to_markdown() — Provides the “to markdown” logic.
- _render_unreachable_appendix() — (internal helper) builds / writes the unreachable appendix step.
- _render_threat_model() — (internal helper) builds / writes the attack scenario model step.
- _render_metrics() — (internal helper) builds / writes the metrics value.
- _render_scan_health() — (internal helper) builds / writes the scan health step.
- _render_scope_appendix() — (internal helper) builds / writes the in-scope set appendix step.
Functions
- _demote_md_headings() — (internal helper) reads and cleans up the Markdown report headings step.
- _md_cell() — (internal helper) Provides the “Markdown report cell” logic.
- _norm() — (internal helper) reads and cleans up the norm value.
- _coerce_enum() — (internal helper) reads and cleans up the enum value.
- _coerce_int() — (internal helper) reads and cleans up the int value.
- _coerce_confidence() — (internal helper) reads and cleans up the confidence value.
See also: HLD · LLD · Data Flow · module index.