How aashmit-mckenzie-college/hunter works
1. What this repo is
- Hunter is a local-first static analysis platform for PHP codebases, with WordPress as a first-class profile.
- The core runtime is the Python package under src/hunter; the UI is a separate React/Vite dashboard in dashboard/.
2. Main entrypoints
- CLI: src/hunter/cli/main.py runs scans directly against a path.
- API backend: src/hunter/api/main.py exposes scan/upload/GitHub endpoints for the dashboard.
- Dashboard: the React app talks only to the API; it is not the analysis engine.
3. Primary scan flow
- The default pipeline is: ingestion → parse + lift → graph construction → catalog/adapters → analysis → rule evaluation → enrichment → reports.
- This is the deterministic static path described in the README; everything else layers on top of it.
4. Ingestion boundary
- src/hunter/ingest/ walks the target tree, applies limits, and writes a snapshot/manifest of the codebase.
- This stage defines the “what is being analyzed” boundary and feeds the rest of the system with a bounded, reproducible file set.
5. Parsing and semantic lift
- src/hunter/parse/ handles language detection, parsing, line indexing, and export of the intermediate representation.
- The lift code (lift.py, lift_v2.py) produces the IR v2 semantic layer that downstream graph and analysis components consume.
- Parsing is parallelized with worker infrastructure in src/hunter/concurrency/.
6. Graph substrate
- src/hunter/graph/ is the structural backbone: graph building, integrity checks, layered schema support, imports, and exports.
- The repo carries graph migrations and uses a schema v3 / layered graph model; Neo4j integration exists for graph metadata/bulk export, but the analysis pipeline also works with in-memory graph structures.
- The graph is the shared contract between parsing, semantic resolution, taint, and rule evaluation.
7. Semantic and security analysis
- src/hunter/analysis/semantic/ adds CFG, SSA, resolver logic, and interprocedural linking.
- src/hunter/analysis/taint/ performs path-sensitive taint analysis.
- src/hunter/analysis/security/ and src/hunter/verify_static/ hold higher-level security reasoning and static verification hooks.
- WordPress-specific behavior lives in src/hunter/wp/ and is injected through profile/adaptor logic rather than hardcoded into the generic PHP path.
8. Rules and profiles
- Rule evaluation is YAML-driven under src/hunter/analysis/rules/, with catalogs and packs for generic PHP, WordPress, and full scans.
- The system uses graph queries and evaluators to map findings to metadata like OWASP/CWE and to switch behavior based on scan profile (auto, generic-php, wordpress, full).
9. Confidence, enrichment, and gating
- src/hunter/confidence/ computes confidence scores from weights/config.
- src/hunter/agents/ contains the enrichment and verification scaffolding, including gates and LLM-backed helpers.
- In the default product, these components annotate or filter findings after deterministic analysis; in agent mode they can add additional reasoning, but they are deliberately separated from the core scanner.
10. Reporting and artifacts
- src/hunter/reporting/ turns findings into grouped human-readable summaries.
- The pipeline writes artifacts to output/<scan>/, including findings JSON, grouped triage reports, evidence excerpts, and semantic graph exports.
- This output directory is the main boundary between the analysis engine and consumers.
11. Persistence and dashboard backend
- src/hunter/persistence/ stores scan/job state in SQLite or Postgres.
- src/hunter/api/services/scan_worker.py runs scans in a background process for the dashboard.
- The API also integrates with GitHub cloning and PDF report generation, making the backend a thin orchestration layer around the same scan engine.
12. Configuration and external dependencies
- Runtime behavior is driven by config/default.yaml plus environment variables.
- Optional external services include:
- GitHub for cloning/importing repos into scans.
- LLM providers for agent mode, configured separately in config/agents.local.yaml.
- Neo4j for graph-related metadata/export paths.
- The README emphasizes that agent configuration is file-only and gated by hunter agents test.
13. Operational shape
- The system is designed for deterministic, reproducible local scans with parallel parsing/ingestion and serial high-risk steps like CFG/taint when needed.
- Observability hooks exist in src/hunter/observability/, and the repo includes tests/fixtures for PHP and WordPress inputs to validate the analysis pipeline end to end.
Main entry points: rules Rules engine · graph Graph core · parse Parsing · orchestration Orchestration
Components 22
Core engine
Python analysis runtime and scan pipeline
- CLI · Runs local scans against a path
src/hunter/cli/main.py - Ingestion · Walks targets, applies limits, and snapshots input files
src/hunter/ingest - Parsing · Detects languages, parses PHP, and builds line indexes
src/hunter/parse - IR lift · Produces the v2 intermediate representation
src/hunter/parse/lift_v2.py - Graph core · Builds the layered structural graph and validates integrity
src/hunter/graph - Semantic analysis · Constructs CFG, SSA, and resolver-linked semantics
src/hunter/analysis/semantic - Taint analysis · Performs path-sensitive interprocedural taint tracking
src/hunter/analysis/taint - Security checks · Higher-level security reasoning and static verification hooks
src/hunter/analysis/security - Rules engine · Loads YAML packs and evaluates graph-driven findings
src/hunter/analysis/rules - Reporting · Groups findings into human-readable summaries
src/hunter/reporting - WordPress profile · Injects WordPress-specific semantics into the generic PHP pipeline
src/hunter/wp
Dashboard stack
React UI and API orchestration
- API · Exposes scan, upload, and GitHub endpoints
src/hunter/api/main.py - Scan worker · Executes scans for the dashboard backend
src/hunter/api/services/scan_worker.py - Dashboard · Browser UI for scan navigation and reports
dashboard/src/App.tsx - GitHub import · Clones or imports repositories for scans
src/hunter/api/services/github_client.py
Platform support
Persistence, config, observability, and external integrations
- Confidence · Computes finding confidence from weights and config
src/hunter/confidence/engine.py - Agents · LLM-backed enrichment, gating, and verification scaffolding
src/hunter/agents - Persistence · Stores scan and job state in SQLite or Postgres
src/hunter/persistence - Orchestration · Coordinates scan lifecycle, status, and lineage
src/hunter/orchestration - Config · Loads default YAML and environment-driven settings
src/hunter/settings.py - Observability · Metrics and tracing for pipeline execution
src/hunter/observability - Neo4j export · Optional graph metadata and bulk export path
src/hunter/graph/neo4j_client.py
Connections 28
- CLI → Ingestion: starts · CLI begins a local scan from a filesystem path
- API → Scan worker: dispatches · API hands scan jobs to the background worker
- Scan worker → Orchestration: runs · Worker uses orchestration to manage scan lifecycle
- Dashboard → API: calls · Dashboard reads and controls scans through the API
- GitHub import → API: feeds · GitHub integration supplies repo content to scan endpoints
- Orchestration → Ingestion: coordinates · Scan control kicks off bounded repository ingestion
- Ingestion → Parsing: passes files · Snapshot and manifest feed the parsing stage
- Parsing → IR lift: produces · Parsing emits the semantic IR v2 layer
- Parsing → Graph core: exports · Parser-derived structure is exported into graph form
- IR lift → Graph core: builds · Semantic lift is materialized into the shared graph substrate
- Graph core → Semantic analysis: supports · Structural graph is consumed by resolver and semantic analysis
- Semantic analysis → Taint analysis: enables · CFG, SSA, and resolution inform taint propagation
- Semantic analysis → Security checks: feeds · Semantic facts are reused by higher-level security checks
- Graph core → Rules engine: queried by · Rule packs evaluate findings through graph queries
- Taint analysis → Rules engine: produces findings · Taint results are scored and matched against rules
- Security checks → Rules engine: augments · Security reasoning contributes additional evaluation context
- Rules engine → Confidence: scores · Rules and findings are weighted into confidence scores
- Rules engine → Agents: hands off · Deterministic findings can be enriched or verified by agents
- Agents → Reporting: annotates · Agent outputs may filter or enrich report content
- Rules engine → Reporting: renders · Evaluated findings become grouped reports and summaries
- Reporting → Persistence: stores · Scan artifacts and job state are persisted for dashboard access
- Orchestration → Persistence: records · Lifecycle and status data are written to the job store
- Config → API: configures · Runtime settings drive backend behavior
- Config → CLI: configures · Runtime settings drive CLI scan behavior
- Observability → Orchestration: watches · Metrics and tracing observe scan execution
- Graph core → Neo4j export: exports to · Optional graph export and metadata integration
- WordPress profile → Parsing: adapts · WordPress-specific parsing and semantics extend the generic PHP path
- WordPress profile → Rules engine: profiles · WordPress rules and catalogs change evaluation behavior