cybergraph 0.1.0

Cybersecurity knowledge graph for code review with evidence-backed answers

CyberGraph

Security review for codebases, powered by knowledge graphs.

CyberGraph maps a repository into a cybersecurity knowledge graph so developers can inspect security layers, risky code paths, scanner findings, and evidence-backed answers without reading the whole codebase by hand.

Why this exists

Security scanners are useful, but their output is usually flat: a file, a line, a rule, and a warning. Developers still have to answer the hard questions:

• Is this issue reachable from production code?
• Is there authentication before this sensitive action?
• Did this pull request affect a security boundary?
• Which scanner findings matter first?

CyberGraph is designed to connect those dots.

Current capabilities

• Builds a local SQLite graph in .cybergraph/graph.db.
• Analyzes five languages: Python (FastAPI/Flask/Django), JavaScript/TypeScript (Express/Next.js), Go (net/http, Gin, Echo), Java (Spring), and C# (ASP.NET Core) — through a shared analyzer contract with graceful fallback for the rest.
• Extracts functions, calls, route entrypoints, auth/authz guards, validators, user-input/data-flow edges, secret access/exposure, cloud resources, and sensitive sink calls.
• Cross-file, interprocedural attack paths (route → service → repository → sink) with confidence, sanitizer-barrier flags, taint/data-reachability, risk scores, and fix guidance; a --shallow mode reproduces intra-function traversal for comparison.
• Interactive, offline HTML report built for first-time readers: a dark-mode-first neon graph explorer (glowing, security-typed nodes with a light/dark toggle), NODE/EDGE/ZONE explainer cards, a guided first view that opens on the top attack path with a plain-language narrative, a security-zones view (Attack Surface → Guards → Logic → Sensitive Sinks), search, layer/severity filters, a details panel with source drill-down, and entrypoint→sink path highlighting (Cytoscape.js, fully inlined).
• Exec-first report posture: an A–F security grade with a one-line verdict and severity-distribution bar, a since-last-scan delta strip (new/regressed/fixed), findings grouped into expandable rule cards, an honest findings-cap footer, and a print stylesheet for clean PDF export.
• Evidence-grounded answers (cybergraph explain) with file/line/rule/path citations, attack-path narratives, remediation guidance, and a high/medium/low/insufficient confidence level — never claims a vulnerability without supporting evidence, and works with no LLM.
• Optional, local-only by default LLM phrasing via configurable providers (Anthropic Claude, OpenAI, Kimi 2.6) constrained to retrieved evidence.
• Maps dependency manifests and lockfiles across npm, Python, Go, Maven/Gradle, and .NET ecosystems.
• Imports OSV Scanner, npm audit, Semgrep JSON, SARIF, and Gitleaks reports into the same graph; enriches vulnerabilities from offline EPSS/KEV/CVSS/advisory JSON; exports findings as SARIF.
• Correlates Terraform resources to application code references so public cloud exposure can be connected to reachable routes, sinks, and dependency risk.
• Exposes MCP tools for AI coding assistants.

Install

# From PyPI (once published):
pipx install cybergraph                 # isolated CLI install
python -m pip install cybergraph        # or into the current environment

# Optional extras:
python -m pip install "cybergraph[mcp]" # MCP server for AI assistants
python -m pip install "cybergraph[llm]" # Anthropic / OpenAI / Kimi providers
python -m pip install "cybergraph[all]" # everything optional

# From a clone (development):
python -m pip install -e ".[dev]"

Supported Python: 3.10, 3.11, 3.12, 3.13.

Quick start

cybergraph quickstart .        # zero-to-report: init, build, analyze, open report
cybergraph init .
cybergraph doctor .
cybergraph analyze .          # build + run every analysis, print top risks
cybergraph history .          # what's new / fixed / regressed since the last scan
cybergraph config show .      # inspect effective config + LLM/graph state
cybergraph build path/to/repo
cybergraph ask "Which functions reach SQL execution?" --repo path/to/repo
cybergraph explain "Which routes reach SQL execution?" --repo path/to/repo
cybergraph paths --repo path/to/repo
cybergraph layers --repo path/to/repo
cybergraph secrets path/to/repo
cybergraph cloud-code path/to/repo
cybergraph top-risks path/to/repo
cybergraph scan path/to/repo               # lightweight built-in analyzers, no graph needed
cybergraph triage path/to/repo             # rank findings; --llm suppresses false positives
cybergraph sca path/to/repo                # prioritize dependency CVEs by reachability
cybergraph infer-specs path/to/repo        # propose custom taint sinks/sources
cybergraph iac-paths path/to/repo          # public exposure -> privileged IaC resource
cybergraph investigate path/to/repo --output investigation.md
cybergraph strix-plan path/to/repo --output strix-plan.md
cybergraph import-strix strix_runs/<run> --repo path/to/repo
cybergraph export-json path/to/repo --output graph.json
cybergraph opengraph path/to/repo --output opengraph.json   # BloodHound OpenGraph interop
cybergraph review --base main --repo path/to/repo
cybergraph pr-comment --base main --repo path/to/repo --output cybergraph-pr-comment.md
cybergraph visualize path/to/repo
cybergraph sarif --repo path/to/repo --output cybergraph.sarif

Typical build output:

Built security graph for examples/vulnerable-fastapi
Nodes: 15 | Edges: 28 | Findings: 1

Typical PR comment sections:

Risk: medium
What Changed: CyberGraph detected 2 entrypoints, 1 sensitive sink edge, 1 finding in changed files.
What To Check Next: Confirm changed entrypoints require authentication or authorization when needed.

Import scanner results:

cybergraph import-report semgrep.json --repo path/to/repo
cybergraph import-vulns osv-results.json --repo path/to/repo
cybergraph enrich-vulns advisory-intel.json --repo path/to/repo
cybergraph ask "Which high severity findings involve secrets?" --repo path/to/repo

Validate reachable risk with an AI pentester (Strix):

# 1. Turn CyberGraph's reachable paths into a focused Strix scope brief
cybergraph strix-plan path/to/repo --output strix-plan.md

# 2. Run Strix yourself against that brief (needs Docker + an LLM key):
#      strix -n -t path/to/repo -m quick --instruction-file strix-plan.md
#    ...or let CyberGraph orchestrate it end-to-end (optional, opt-in):
cybergraph strix-run path/to/repo --scan-mode quick

# 3. Import Strix's PoC-validated findings back into the graph
cybergraph import-strix strix_runs/<run-name> --repo path/to/repo
cybergraph top-risks path/to/repo   # validated findings rank at the top

CyberGraph tells Strix where to attack (reachable routes and sinks), and Strix tells CyberGraph what is actually exploitable (validated with a working PoC). Strix is never a dependency — the strix-run bridge only activates when the strix binary and Docker are both present, so the offline-by-default workflow is unchanged.

Suppress accepted findings:

def test_fixture():
    # cybergraph: ignore CG-SINK-CALL accepted test-only query
    return db.execute("select 1")

Or configure repository-level suppressions:

[suppressions]
rules = ["CG-SINK-CALL"]
paths = ["legacy/**"]

Suppressions hide findings, but the graph still keeps edges such as REACHES_SINK so reviewers can inspect the real code path.

Example questions

Which endpoints can reach SQL execution?
What changed in this PR that affects authentication?
Where are secrets loaded and passed into network clients?
Which vulnerable dependency is reachable from production code?
Are there route handlers that reach shell or file writes?

Try the demo

cybergraph build examples/vulnerable-fastapi
cybergraph ask "Which routes reach SQL execution?" --repo examples/vulnerable-fastapi
cybergraph visualize examples/vulnerable-fastapi --output cybergraph-report.html

MCP tools

Install with the optional MCP extra and run the server:

python -m pip install -e ".[mcp]"
cybergraph-mcp

Available tools:

• build_security_graph_tool
• query_security_graph_tool
• explain_attack_path_tool
• grounded_security_answer_tool (cited, confidence-scored, local-only)
• analyze_repo_tool (build + full analysis in one call)
• top_risks_tool
• secret_exposures_tool
• prioritize_dependencies_tool (reachability-ranked SCA)
• iac_attack_paths_tool
• import_scanner_report_tool
• import_vulnerabilities_tool

Project direction

CyberGraph is intentionally security-first. It is not trying to be a general code graph with security keywords sprinkled on top. The goal is to model controls, attack paths, trust boundaries, scanner findings, and code evidence as one graph.

See:

• Architecture
• Getting started
• Five-minute tutorial
• Security ontology
• Product plan
• GitHub Action

Status

Beta. CyberGraph analyzes five languages, builds interprocedural attack paths, imports and enriches scanner findings, correlates IaC to code, ships an interactive HTML report, and exposes an MCP surface for AI assistants. The graph store, analyzers, evidence retrieval, and report are stable; the public API and finding rules may still change before 1.0.