Module: vvaharness/rules
Role. First-party CWE knowledge plus a compiler that turns external corpora (Semgrep/CodeQL/FindSecBugs) into VVAH rule packs.
Size. 4 files · ~2,508 LOC.
This package is VVAH's security knowledge base. It carries first-party knowledge of weakness types (CWE) and can compile external rule sets into the compact format the pipeline uses, so the analysis is grounded in established security rules rather than guesswork alone.
Explain-it-simply. The reference library of known weakness patterns, plus a tool to import rules from other security scanners.
Data-flow (this module)
Technical details
__init__.py exposes CweKB (first-party CWE knowledge + external overlays).
build_kb.py (~1,670 LOC) is the offline corpus→*.kb.yaml compiler with extractors for Semgrep,
FindSecBugs, and CodeQL (including MAD signatures). families.py is the shared semantic-family /
CWE / language vocabulary (norm_cwe, canonical_family, owasp_labels). generic_pack.py
builds a generic OWASP/CWE taint KB, optionally LLM-refined.
File map (quick scan)
| File | LOC | Purpose |
|---|---|---|
rules/__init__.py |
255 | First-party CWE knowledge plus explicit external overlays. |
rules/build_kb.py |
1667 | Offline corpus → *.kb.yaml compiler. |
rules/families.py |
142 | Shared semantic-family, CWE and language vocabulary for the rule/callgraph stages. |
rules/generic_pack.py |
444 | Generic OWASP/CWE taint knowledge base. |
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.
rules/__init__.py
255 LOC. First-party CWE knowledge plus explicit external overlays.
Classes
- CweKB — Represents the “CweKB” data/behaviour used in this file.
- __len__() — Python built-in method (__len__).
- __contains__() — Python built-in method (__contains__).
- load() — Looks up / reads the load value.
- _overlay_list() — (internal helper) Provides the “settings override list” logic.
- _kb_files() — (internal helper) Provides the “knowledge base files” logic.
- _read() — (internal helper) looks up / reads the read value.
- _merge() — (internal helper) adds detail to the merge value.
- for_cwes() — Provides the “for cwes” logic.
- prompt_block() — Provides the “prompt block” logic.
Functions
- _filter_lang() — (internal helper) checks / decides the lang value.
rules/build_kb.py
1667 LOC. Offline corpus → *.kb.yaml compiler.
Functions
- _compact() — (internal helper) Provides the “compact” logic.
- _scoped() — (internal helper) Provides the “scoped” logic.
- _entry() — (internal helper) Provides the “entry” logic.
- _flatten() — (internal helper) reads and cleans up the flatten value.
- extract_semgrep() — Reads and cleans up the a security scanner value.
- extract_findsecbugs() — Reads and cleans up the a security scanner value.
- _ql_role() — (internal helper) Provides the “ql role” logic.
- extract_codeql() — Reads and cleans up the a security scanner value.
- _mad_signature() — (internal helper) Provides the “model-of-attack data signature” logic.
- _extract_codeql_mad() — (internal helper) reads and cleans up the a security scanner model-of-attack data step.
- _collapse() — (internal helper) Provides the “collapse” logic.
- write_kb() — Builds / writes the knowledge base value.
- _guess_ep_kind() — (internal helper) Provides the “guess ep kind” logic.
- _slug() — (internal helper) Provides the “short name” logic.
- _guess_sink_kind() — (internal helper) Provides the “guess dangerous operation kind” logic.
- _canonical_family() — (internal helper) Provides the “canonical family” logic.
- _semantic_family_from_sink() — (internal helper) Provides the “semantic family from dangerous operation” logic.
- _semantic_family_from_source() — (internal helper) Provides the “semantic family from untrusted input point” logic.
- _owasp_2025_labels() — (internal helper) Provides the “owasp 2025 labels” logic.
- _source_meta() — (internal helper) Provides the “untrusted input point meta” logic.
- _sink_meta() — (internal helper) Provides the “dangerous operation meta” logic.
- _print_rule_quality_summary() — (internal helper) Provides the “print rule quality summary” logic.
- _parse_lang_list() — (internal helper) reads and cleans up the lang list step.
- _load_rule_file() — (internal helper) looks up / reads the rule file step.
- _normalize_callgraph_rule() — (internal helper) reads and cleans up the map of which code calls what rule step.
- _prepare_callgraph_rules() — (internal helper) builds / writes the map of which code calls what rules step.
- _strip_taint_keys() — (internal helper) Provides the “strip untrusted-data flow keys” logic.
- _lift_pattern_sources() — (internal helper) Provides the “lift pattern untrusted input points” logic.
- extract_semgrep_source_rules() — Reads and cleans up the a security scanner untrusted input point rules step.
- _lift_pattern_sinks() — (internal helper) Provides the “lift pattern dangerous operations” logic.
- extract_semgrep_sink_rules() — Reads and cleans up the a security scanner dangerous operation rules step.
- _git_sha_for() — (internal helper) Provides the “version control content hash for” logic.
- _artifact_provenance() — (internal helper) Provides the “artifact provenance” logic.
- write_sources_yaml() — Builds / writes the untrusted input points config file step.
- write_sinks_yaml() — Builds / writes the dangerous operations config file step.
- _import_pattern() — (internal helper) Provides the “import pattern” logic.
- _call_pattern() — (internal helper) Provides the “call pattern” logic.
- extract_codeql_source_rules() — Reads and cleans up the a security scanner untrusted input point rules step.
- extract_codeql_sink_rules() — Reads and cleans up the a security scanner dangerous operation rules step.
- _fsb_sink_langs() — (internal helper) Provides the “fsb dangerous operation langs” logic.
- _jvm_to_source_class() — (internal helper) Provides the “jvm to untrusted input point class” logic.
- extract_findsecbugs_sink_rules() — Reads and cleans up the a security scanner dangerous operation rules step.
- main() — Runs the main value.
rules/families.py
142 LOC. Shared semantic-family, CWE and language vocabulary for the rule/callgraph stages.
Functions
- norm_cwe() — Reads and cleans up the weakness type value.
- canonical_family() — Provides the “canonical family” logic.
- owasp_labels() — Provides the “owasp labels” logic.
- resolve_semantic_family() — Checks / decides the semantic family step.
- canonical_lang() — Provides the “canonical lang” logic.
rules/generic_pack.py
444 LOC. Generic OWASP/CWE taint knowledge base.
Functions
- _generic_entries() — (internal helper) Provides the “generic entries” logic.
- _generic_llm_model() — (internal helper) Provides the “generic AI model model” logic.
- refine_generic_entries_with_llm() — Provides the “refine generic entries with AI model” logic.
- write_generic_kb() — Builds / writes the generic knowledge base step.
See also: HLD · LLD · Data Flow · module index.