Skip to content

FILE_GUIDE

Jump to bottom
Matthew A. Davis edited this page May 8, 2026 · 1 revision

File Guide (Maintainership)

This guide focuses on architecture-defining files in the AttackMap core repo.

Where to start

  • Returning maintainer: read CLI, analyzer contracts/loaders, scanner, translation, and threat-model sections first.
  • New contributor: use this with Module Map and Analyzer Ecosystem.
  • Security engineer: focus on analysis, threat-model, and reporting sections.

Repository root referenced below:

  • /Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap

CLI and orchestration

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/cli.py

  • Purpose:
    • Main CLI entrypoint and top-level pipeline orchestration.
  • Key functions:
    • analyze(...)
    • modules(...)
  • Important inputs/outputs:
    • Inputs: repo path, output dir, requested module names.
    • Outputs: triggers full analysis and report writing.
  • Dependencies:
    • analyzers.py, graph.py, recon_to_analysis.py, analyzer.py, defensive_review.py, report.py.
  • Why this file exists:
    • Central place for user-facing flow and command UX.
  • What breaks if changed carelessly:
    • End-to-end execution order, module selection/install behavior, output artifact generation and paths.

Analyzer contracts, loading, and execution

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/analyzer_contracts.py

  • Purpose:
    • Canonical analyzer contract and metadata model.
  • Key classes/functions:
    • AnalyzerMetadata
    • AnalyzerProtocol
    • AnalyzerRepositoryModule
    • AnalyzerResult alias
    • normalize_analyzer_metadata(...)
  • Important inputs/outputs:
    • Normalizes metadata from built-ins/plugins.
  • Dependencies:
    • recon_models.ScanResult.
  • Why this file exists:
    • Stable contract for built-in and plugin analyzers.
  • Careless-change risk:
    • Plugin loading failures, metadata incompatibility, broken analyzer registry behavior.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/sdk/contracts.py

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/sdk/models.py

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/sdk/__init__.py

  • Purpose:
    • SDK-style re-export surface used by external analyzer packages.
  • Key exports:
    • Contracts + result/recon models.
  • Transitional/compat note:
    • Mostly wrappers around core models/contracts for import stability.
  • Careless-change risk:
    • External analyzer packages break at import-time.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/analyzers.py

  • Purpose:
    • Analyzer registry, discovery, selection, installation, execution, and merge.
  • Key classes/functions:
    • Built-ins: BuiltinPythonWebAnalyzer, BuiltinJavaScriptWebAnalyzer, DefaultAnalyzer
    • Discovery/loading: discover_installed_analyzers(...), _load_discovered_analyzer(...)
    • Selection/install: select_requested_analyzers(...), install_analyzer_module(...)
    • Execution/merge: analyze_repository(...), resolve_run_analyzers(...), merge_analyzer_results(...)
    • Metadata listing: get_available_modules(...), get_available_repository_modules(...)
  • Important inputs/outputs:
    • Input: analyzer objects (built-in + entry points), repo path.
    • Output: merged ScanResult.
  • Dependencies:
    • analyzer_contracts/sdk, scanner.py, subprocess, importlib.metadata.entry_points.
  • Why this file exists:
    • Owns analyzer lifecycle and makes plugin architecture usable.
  • Transitional/compat note:
    • Contains legacy file-level analyzer helpers (AnalyzerSignals, RouteAnalyzer, etc.) alongside repo-level analyzers.
  • Careless-change risk:
    • Duplicate/invalid analyzer loading, install path regressions, merge dedupe regressions, module CLI breakage.

Generic scanner and recon models

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/scanner.py

  • Purpose:
    • Generic heuristic code scanning for routes/calls/db/auth/secrets.
  • Key functions:
    • scan_repo(...)
    • extract_routes(...)
    • should_scan(...), should_scan_with_suffixes(...)
  • Important inputs/outputs:
    • Input: repo root and optional suffix filter.
    • Output: ScanResult with generic signals.
  • Dependencies:
    • sdk.models, regex pattern constants.
  • Why this file exists:
    • Baseline analyzer behavior and built-in fallback coverage.
  • Transitional/compat note:
    • Explicitly constrained to generic-only behavior; ecosystem overlays moved out.
  • Careless-change risk:
    • Route extraction regressions, signal noise increase, baseline analyzer quality drop.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/models.py

  • Purpose:
    • Core Pydantic models for recon signals and higher-level outputs.
  • Key classes:
    • Recon: Route, ExternalCall, DatabaseHint, AuthHint, SecretHint
    • Migrated hint buckets: ServiceHint, EdgeHint, EntrypointHint, ProtocolHint, FrameworkHint
    • Analysis: AttackSurface, Finding, AttackPath
    • Aggregate: ScanResult
  • Why this file exists:
    • Single source of truth for data shape.
  • Transitional/compat note:
    • Mid-migration away from auth_hints as generic hint bus.
  • Careless-change risk:
    • Broad cross-module breakage, schema/report/test failures.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/recon_models.py

  • Purpose:
    • Compatibility re-exports for recon/result models.
  • Transitional/compat note:
    • Migration layer; likely reducible when imports stabilize.
  • Careless-change risk:
    • Import path breakage across core and plugins.

Translation and analysis flow

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/recon_to_analysis.py

  • Purpose:
    • Canonical recon-to-analysis translation gateway.
  • Key functions:
    • translate_recon(scan)
    • to_attack_surface(...)
    • to_findings(...)
    • to_attack_paths(...)
    • _auth_filtered_scan(...)
  • Important inputs/outputs:
    • Input: ScanResult
    • Output: AnalysisOutputs (surfaces/findings/paths)
  • Dependencies:
    • analyzer.py, threat_model.py.
  • Why this file exists:
    • Formal translation boundary and stability point.
  • Transitional/compat note:
    • Heavy compatibility filtering for overloaded auth_hints.
  • Careless-change risk:
    • Inconsistent surfaces/findings/path semantics and duplicated translation behavior.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/analyzer.py

  • Purpose:
    • Attack-surface classification and architecture/attack-surface markdown summaries.
  • Key functions:
    • identify_attack_surfaces(...)
    • summarize_architecture(...)
    • summarize_attack_surface(...)
  • Inputs/outputs:
    • Input: ScanResult (+ optional precomputed surfaces for summaries)
    • Output: AttackSurface[] + markdown strings
  • Dependencies:
    • models.py, networkx graph output.
  • Why this file exists:
    • Human-readable architecture/attack-surface interpretation stage.
  • Transitional/compat note:
    • Uses broader supporting hint buckets for exposure heuristics but auth-focused display for auth_signals.
  • Careless-change risk:
    • Category/risk/exposure drift affecting findings, paths, reviews, and JSON artifacts.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/threat_model.py

  • Purpose:
    • Findings generation and attacker-path generation.
  • Key functions:
    • generate_findings(...)
    • generate_attack_paths(...)
  • Key internal chain builders:
    • _build_service_chains(...)
    • _build_atproto_chains(...)
    • _build_probable_chains(...)
    • Helper extraction/inference functions (_extract_prefixed_hints, _extract_edge_hints, _file_service_map, etc.)
  • Inputs/outputs:
    • Input: ScanResult and optionally attack surfaces.
    • Output: Finding[], AttackPath[]
  • Dependencies:
    • analyzer.identify_attack_surfaces.
  • Why this file exists:
    • Core attacker-perspective reasoning engine.
  • Transitional/compat note:
    • Reads both dedicated hint buckets and legacy auth_hints prefixes.
  • Careless-change risk:
    • Major security-output regressions, noisy/implausible findings, broken chain narratives.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/graph.py

  • Purpose:
    • Coarse trust-boundary/system graph generation.
  • Key function:
    • build_graph(scan)
  • Why this file exists:
    • Quick architecture visualization primitives used in summaries.
  • Careless-change risk:
    • Architecture summary trust-boundary sections lose coherence.

Defensive review and reporting artifacts

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/defensive_review.py

  • Purpose:
    • Defensive-review markdown synthesis with prioritization/ranking.
  • Key function:
    • render_defensive_review(...)
  • Important internals:
    • scoring: _surface_priority, _path_priority, _finding_priority
    • evidence/source-quality classification helpers
  • Inputs/outputs:
    • Input: scan + surfaces + findings + paths
    • Output: defensive review markdown
  • Why this file exists:
    • Product-facing security triage narrative.
  • Careless-change risk:
    • Credibility/prioritization quality regressions.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/review_json.py

  • Purpose:
    • Stable machine-readable defensive review artifact generation.
  • Key function:
    • build_defensive_review_json(...)
  • Inputs/outputs:
    • Input: scan/surfaces/findings/paths
    • Output: structured JSON dict
  • Why this file exists:
    • Source-of-truth payload for downstream LLM/eval/automation use.
  • Careless-change risk:
    • Schema and downstream consumer breakage.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/context_pack.py

  • Purpose:
    • Context pack builder for LLM review layer.
  • Key function:
    • build_review_context_pack(...)
  • Why this file exists:
    • Packages review JSON + analyzer metadata + source-quality and domain hints.
  • Careless-change risk:
    • Loss of grounding/quality hints for model consumers.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/review_prompts.py

  • Purpose:
    • Prompt template rendering for LLM defensive review generation.
  • Key exports:
    • SYSTEM_PROMPT_TEMPLATE, USER_PROMPT_TEMPLATE
    • render_system_prompt, render_user_prompt, render_review_prompts
  • Why this file exists:
    • Enforces evidence-first, defensive, non-inventive prompting constraints.
  • Careless-change risk:
    • Higher hallucination/off-policy output risk.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/report.py

  • Purpose:
    • Write all output artifacts + console summary.
  • Key functions:
    • write_reports(...)
    • render_console_summary(...)
  • Outputs:
    • architecture.md
    • attack-surface.md
    • defensive-review.md
    • defensive-review.json
    • review-context-pack.json
    • attackmap-report.json
  • Why this file exists:
    • Single output writer boundary.
  • Careless-change risk:
    • Missing/invalid artifacts and broken CLI user expectations.

Evaluation and schemas

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/review_eval.py

  • Purpose:
    • Lightweight local evaluation harness for review quality.
  • Key functions:
    • evaluate_review_text(...)
    • run_evaluation(...)
    • run_evaluation_suite(...)
  • Why this file exists:
    • Regression checks for grounding, observed/inferred discipline, recommendation usefulness, false-positive control.
  • Careless-change risk:
    • Silent quality regressions and weaker product validation loop.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/schemas/defensive-review.schema.json

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/schemas/review-context-pack.schema.json

  • Purpose:
    • Contract checks for generated JSON artifacts.
  • Careless-change risk:
    • Mismatch between runtime artifact structure and contract validation.

Tests that define intended behavior (high-value)

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/tests/test_scanner.py

  • Defines scanner extraction expectations and generic-only behavior.
  • Transitional signal:
    • asserts scanner does not emit node-service/atproto overlays.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/tests/test_analyzers.py

  • Defines analyzer discovery/selection/install/metadata/merge behavior.
  • Includes merge behavior for new hint buckets.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/tests/test_shared_contract_imports.py

  • Defines contract import stability across legacy + SDK paths.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/tests/test_recon_to_analysis.py

  • Defines canonical translation flow behavior and consistency.
  • Covers auth filtering and path-generation expectations.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/tests/test_analyzer.py

  • Defines attack-surface classification behavior.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/tests/test_threat_model.py

  • Defines finding/path generation behavior and chain quality expectations.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/tests/test_defensive_review.py

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/tests/test_review_json.py

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/tests/test_context_pack.py

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/tests/test_review_prompts.py

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/tests/test_review_eval.py

  • Define defensive review layer behavior, artifact semantics, and eval harness expectations.

/Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/tests/test_artifact_schemas.py

  • Defines schema conformance requirements for JSON outputs.

Transitional/compatibility-heavy files (explicit callout)

  1. /Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/recon_to_analysis.py
  • Prefix-based auth filtering + migrated bucket suppression.
  1. /Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/threat_model.py
  • Dual-read of legacy and new hint lanes.
  1. /Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/analyzer.py
  • Mixed use of auth-only and supporting hints.
  1. /Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/recon_models.py

and /Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/sdk/*

  • Re-export compatibility surfaces.
  1. /Volumes/Dev/repos/GitLab/matthewd.xyzAI/attackmap/src/attackmap/analyzers.py
  • Combined old file-level helper classes with newer repo-level analyzer architecture.

Migrated from https://gitlab.com/matthewd.xyzAI/AttackMap/-/wikis/docs/FILE_GUIDE.

Clone this wiki locally