cpguard - Open-source CPG-based interprocedural taint analy

项目说明

<p align="center">
<img src="assets/icon.png" width="128" alt="CPGuard"/>
</p>
<h1 align="center">CPGuard</h1>

<p align="center">
<b>Air-gapped security assessment, from source code to the finished report</b><br/>
_{CPG-based taint analysis · LLM triage · audit deli generated for you — a desktop tool that ne home}
</p>

<p align="center">
<b>English</b> · <a href="README.ko.md">한국어</a>
</p>

<p align="center">
<img src=" alt="Python 3.11+">
<img src=" alt="Windows / macOS / Linux">
<img src=" alt="Apache-2.0">
<img src=" alt="Django 5.2">
<img src=" alt="11 languages">
<img src=" alt="78 taint rules">
<img src=" alt="tests passing">
<img src=" alt="OWASP Benchmark">
<img src=" alt="LLM">
</p>

<p align="center">
<img src="docs/img/architecture.svg" width="820" alt="CPGuard analysis pipeline"/>
</p>

> CPGuard = CPG (Code Property Graph) + Guard — it guards your code with a property graph, not a pattern list. That graph is why the logo is three connected nodes.

Pattern-matching scanners drown you in false positives. CPGuard goes deeper —
tree-sitter parsing → language-neutral IR → CPG (AST · CFG · def-use · call) → interprocedural taint with function summaries → LLM triage —
then hands the result to a three-pane review screen where a human confirms the .

<p align="center">
<img src="docs/img/workbench.png" width="900" alt="CPGuard review screen — Source→Sink taint flow over the code with the inspector"/>
<br/>
_{review — the <b>Source→Sink</b> taint path highlighted over the real code, with rule, CWE, flow steps and in the inspector.}
</p>

---

✨ Features

Two detection axes

Data flow (taint) — 11 languages: Ja · TypeScript · PHP · Python · Java · Kotlin · Go · Ruby · C/C++ · Swift · C# (27 file extensions, 78 rules).

SQL injection (CWE-89) · command injection (78) · code injection (94) · XSS (79) · path tra (22) · file inclusion (98) · SSRF (918) · open redirect (601) · insecure deserialization (502) · buffer o (120) · format string (134) · LDAP (90) / XPath (643) injection · WebView XSS · Intent redirection (926) · library injection (114).

Patterns (single point) — every language. Hardcoded secrets and keys (798) · PII · TLS disabled (295) · weak hash/cipher (327) · predictable RNG (338) · cookie flags (1004) · debug code.

review screen

Three panes: issue explorer (list · table · source tree) / code / inspector.

Syntax highlighting · command palette (Ctrl+P) · context menu · gutter markers.

Data-flow — the Source→Sink step graph stays in sync with the code .

AI analysis panel — asks about the selected issue with its rule, flow and surrounding code attached automatically.

(confirmed / false positive / fixed / deferred) with auditor notes, rows tinted by , an audit-state filter, and new/resol between scans.

A moves the numbers immediately — marking a finding a false positi or fixed drops the open count and the se badges on the spot. The detection total stays: it is what the scan found, and a person's does not change that.

A rescan inherits the previous — same fingerprint (rule, file, normalised sink code), same audit state and note. The second and third round of an assessment no longer re-judge what was already cleared.

Judge the whole filtered list at once — findings arrive in clusters of the same sink, and nobody clicks through them one at a time.

Filter by what is inside the flow — match calls and along the traced path (whole flow / source / sink, contains or not, regex allowed). Narrow to flows that went through sanitize, then clear them in one action.

Uncertain flows are marked — a flow that passed through a function whose code is not in the analysed set is flagged and filterable, which is the pile to review first.

Similar-issue grouping (same rule, same sink), history (from what, to what, when), and sa.

Running an assessment

Cancel a scan or a batch — a run started by mistake stops instead of being waited out.

Get back to a running scan — a sticky bar links to it from any screen.

Delete scans in bulk — a bad batch lea of rows behind.

Per-project exclusions — path globs, rules and the stated reason are saved and applied to the next scan, and excluded files are ne. What was applied is stored on the scan, so the report reflects the run that produced it.

Scale: one analyst, hundreds of projects

Batch upload — select many zips at once, or upload a single zip containing project zips; each becomes its own project.

Batch progress — a FIFO worker scans projects sequentially with per-project status.

Project portfolio (/projects/) — every project's latest scan in one searchable, sortable, filterable table.

Bulk deli — select projects and download one ZIP with each project's PDF report and xlsx sheet, ready to hand to de.

Assess against the standard your client asks for

Tick the references before the scan starts: MOIS Secure Coding Guide (Korea's public-sector standard) · Electronic Financial Super Regulation web checklist (Korean finance) · Mobile secure coding checklist (draft) · OWASP Top 10 (2021) · CWE. Pick several — real Korean deli report against more than one at a time.

The mapping key is CWE, so the scan runs once and the standards only shape the report — switching or adding references ne rescanning.

Filter the review screen by check item, group the issue list by it, and tick which standards each export carries. The report's *check items* section becomes those standards' full checklists with a per item, and the xlsx gains a *check items* sheet. Items are identified by category and weakness name, the way real assessment deli are written — never by an item number, which differs between editions of the guide. Items that were assessed and came back clean stay in the table — that is the e of what was checked.

A check item with no rule behind it is ne as "pass." Items outside static analysis — directory indexing, admin page exposure, CSRF — are marked *Not assessed*, so the deli ne a check that did not happen.

Findings outside the chosen standard's mapping are reported separately, ne dropped.

Deli you can actually hand over

Consolidated assessment report — tick the projects on the Reports screen and get one submission-ready document co all of them: purpose and legal basis, schedule, tool, assessor, the standards' check items, initial findings → false-positi → final items to remediate, per-project detail (files, lines of code, languages, weaknesses by se), remediation by type, and appendices. Structured like the reports Korean assessment firms actually deliver.

Report templates — name a template and it decides which sections ship (detail, source and flow, re comment, exclusions, applied rules, scope by language) plus the co, header note and logo. Client requirements differ and templates pile up per contract.

Exclusions, applied rules and scope appendices — what was excluded and why, every rule applied including the ones with no findings, and files/lines/findings/density per language. On a checklist-shaped deli "we checked and found nothing" carries as much weight as a finding.

The review become the report. Marking a finding as a false positive or excluding it on the review screen — with the note explaining why — is what turns a raw scanner dump into a deli. Section 3.2 is built from exactly those , and the initial/final totals differ accordingly.

Word (.docx) and PDF. The Word file is the editable master, so the analyst can drop it into the client's template, add on-site opinions, and ship it. Same sections, same tables, same wording as the PDF.

Analysis sheet (xlsx) — the fixed 14-column format Korean clients expect, plus a *check items* sheet.

E is black text on light grey. Assessment reports travel as black-and-white printouts and photocopies and get pasted into the client's own template, so nothing is distinguished by colour alone — se is graded by lightness, read as words.

LLM triage

Claude · ChatGPT (OpenAI) · Gemini. Re- findings for reachability and explains them; provider and model are selectable. Gemini's free tier is enough to try it.

Deli

Assessment report (PDF) — cover, re history, table of contents, scope and methodology, se chart, checklist, per-finding cards (target · description · data-flow steps · impact · remediation · safe example · CWE reference), o assessment, se appendix, and an assessment-history table across runs.

Remediation guide (PDF) · SARIF 2.1.0 · CSV · 14-column analysis sheet (xlsx).

Report metadata (author, organization, client, assessor, period, ) is filled in from Settings.

UX & delivery

Flat modern-IDE design, four themes (Dark / Light / VS Code / Ghidra).

English ⇄ Korean toggle co ser content too — rule messages, PDF report, xlsx sheet, CSV and SARIF.

Offline, clean-machine install — a single exe (PyInstaller + Inno Setup); no Python, no internet, no admin rights.

Nati window (WebView2, falls back to the browser) or a browser dashboard.

---

🖥 Screens

| Dashboard | explorer (charts · filters · pagination) |
|:---:|:---:|
| !Dashboard | !Explorer |
| Status tiles · se distribution · top rules | Se donut · top rule/CWE bars · large-result explorer |

<p align="center">
<img src="docs/img/reports.png" width="780" alt="Reports and exports"/>
<br/>
_{Reports & exports — per-scan assessment report and remediation guide (PDF), SARIF, CS sheet (xlsx).}
</p>

> The review screen (code + Source→Sink flow + inspector) is the hero image above.

---

📦 Install

Installer — Windows (recommended, no Python needed)

Download the latest CPGuard-Setup-*.exe from Releases and run it.
It installs per-user (no admin rights) and installs the WebView2 runtime if missing.

To build the installer yourself:

It also runs portable — copy the dist/CPGuard folder and run CPGuard.exe.

From source — Windows · macOS · Linux

The engine, the web UI and every report format are pure Python and run on all three platforms.
Only the packaged installer and the nati window (WebView2) are Windows-specific.
Korean text in PDF reports needs a Korean font: Windows and macOS have one out of the box, on
Linux install fonts-nanum, or point CPGUARD_PDF_FONT at any TrueType font you prefer.

🚀 Usage

In the dashboard: upload zip(s) → progress screen (step checklist + runtime log) → review and mark →
add an LLM key in ⚙️ Settings to enable AI analysis and triage.

🔁 CI/CD (GitHub Actions)

Scan on every push and PR, upload SARIF to GitHub Code Scanning so new findings appear inline on the code and the PR. A se gate can fail the build.

The CLI gates too: cpguard scan . --sarif out.sarif --fail-on high (exit code 1 at or above that se).
This repository's .github/workflows/cpguard.yml is a working example.

---

🤖 MCP server — AI agents drive it (SAST → dynamic )

An AI coding agent (Claude Code, Cursor) can dri over MCP: scan, pull the
source-to-sink e, explain a rule, and dynamically a finding —
answering the question a static scanner never can, "is this actually exploitable?"

CPGuard does not fire HTTP. Because it knows the sink, it emits a probe plus an
oracle — what to send and, more importantly, what to observe that proves the sink
fired. The agent fires it with its own tools and hands back what it saw; CPGuard
matches that against the oracle and returns a . It is oracle-match, not IAST —
no instrumentation, so it reports "the predicted signal appeared", not "I observed the
real execution path". NOT_REPRODUCED is kept distinct from FALSE_POSITIVE.

Nine tools: scan_file · scan_start / scan_status (async whole-repo audit) ·
finding.list · finding.e · explain · probe.get · .submit ·
(did your fix actually close the flow?). The core opens no socket; only the
agent's own web tools touch the network.

Design, boundaries, and the full tool contract: docs/mcp-ser.md.
Runnable demo: examples/mcp_demo.py.

🧱 Architecture

Sound o — both branches merged, summary fixpoint (recursion and mutual recursion), unknown functions pass taint through.

Integrity reporting — "0 findings" is distinguished from "could not read": parse failures, size limits and syntax errors are recorded and shown.

Read-only, e — the tool ne hides a finding; the final is a human's.

Adding a language is a table, not a fork: one normalizer maps each grammar's nodes onto the shared IR, so the CPG and taint engine stay untouched.

Stack: Python 3.11+ · tree-sitter (11 languages) · Django (SSR) · reportlab (PDF) · openpyxl (xlsx) · SARIF 2.1.0 · LLM SDKs (anthropic / openai / google-genai) · pytest.

📊 Accuracy

Measured against labelled ground truth in eight languages — fi totalling 138,785 cases, of which 76,866 are scored (the rest are categories excluded below). Score = recall − false-positive rate (the official OWASP metric; random guessing = 0.000).

| Corpus | Language | Scored | Recall | Precision | Score |
|---|---|---:|---:|---:|---:|
| OWASP Benchmark v1.2 | Java | 1,572 | 95.8% | 88.7% | 0.826 |
| C# Test Suite | C# | 33,024 | 84.3% | 91.1% | 0.728 |
| OWASP Benchmark for Python | Python | 346 | 82.1% | 83.3% | 0.717 |
| BenchProctor (httplib / standalone) | C++ | 800 | ~79% | 100% | 0.79 |
| BenchProctor (gin / net_http) | Go | 2,000 | ~80% | ~85% | 0.66 |
| BenchProctor (standalone) | C | 500 | 52.0% | 100% | 0.520 |
| BenchProctor (express / koa) | Ja | 2,200 | ~66% | ~78% | 0.47 |
| BenchProctor (express_ts / nestjs) | TypeScript | 2,200 | ~62% | ~79% | 0.45 |
| BenchProctor (rails / sinatra) | Ruby | 2,400 | ~56% | ~81% | 0.43 |
| PHP test suite | PHP | 31,824 | 47.0% | 66.4% | 0.369 |

Read it plainly: Java, C++, Python, C# and Go are at working-tool quality; C, JS/TS and Ruby are usable; PHP is not there yet. Where the score is low it is usually recall, not noise (PHP recall is 47.0%).

read out of a database or a file count as user input by default — that is where second-order injection and stored XSS come from. Pass --trust-stored-data to turn it off. The default was chosen by measurement, not taste: across 15 suites, treating stored data as a source cost nothing anywhere and bought Go 50 extra true positives for 9 extra false ones.

Do not take the 100% precision on C/C++ at face value. Those corpora are small (400-500 cases each) and their safe are generated from exactly two guard idioms (check(x) ? x : default, and "replace with a default when the check fails"). Teaching the engine to read those two took the false positives to zero in one step — that measures how completely the generator's rules were matched, not how real C code is. The 52-80% recall is the more honest signal. Kotlin and Swift have no public labelled corpus at all, so they are covered by idiom tests instead (see below).

Config-only categories (weakrand, crypto, hash, securecookie, trustbound) are not data-flow problems and are excluded rather than counted as free wins. Categories that *are* data-flow problems but that CPGuard has no rule for (NoSQL injection, SSTI, prototype pollution, XXE …) are reported separately from those, so co is not quietly inflated.

The benchmarks drove real engine work. Ja at 0.137 and PHP at 0.001; every point since came from a defect the numbers exposed — taint dying inside try blocks, for-each losing the collection's taint, no path sensitivity at all, container mutations not propagating, comparison results carrying taint, constructor-to-field-to-method flows missing in every language, by-reference output parameters (fgets(buf, …), Decode(&v)) in to a return- model, closures running against an empty en so anything they captured looked clean, and — most recently — applied to a *projection* of the tainted value (if !allowed[url.Parse(x).Hostname()] { reject }) leaving the original tainted, which was 59% of all Go false positives. Each fix is a general analysis technique, not a tweak aimed at the test cases. The full before/after ledger is in bench/README.md.

Where labelled data does not exist (Kotlin, Swift, and any framework a corpus does not cover), CPGuard ships idiom tests instead: 130 minimal reproductions of shapes that are common in real code, run as part of the test suite. They catch a different class of defect than the benchmarks do — TypeScript parameters were carrying their type annotation into the parameter name, which silently removed *every typed function* from interprocedural analysis, and no benchmark score moved when it was fixed.

A second measurement on a real application (DVWA, PHP) is also published. Full methodology, per-category tables and limitations: bench/README.md.

📈 Large codebases

Strategies for extreme scale (20–30 GB of source, 50k+ findings) — sink pre-filtering, incremental and summary caches, the finding DB table, aggregation with scrolling, triage clustering — are in docs/large-scale.md.

🗺️ Roadmap

[x] Taint core, pattern engine, LLM triage, review screen

[x] PDF assessment report and remediation guide · offline installer

[x] Finding DB table + ser pagination · scrolling for large results

[x] Sink pre-filtering · multiprocessing · parse/summary caches · triage clustering

[x] CI/CD — GitHub Action · SARIF → Code Scanning · se gate

[x] Accuracy measured in 8 languages — 5 labelled corpora, 76,866 scored cases (details)

[x] 11 languages — Ja, Go, Ruby, C/C++, Swift, C# added

[x] Batch scanning, project portfolio and bulk deli for hundreds of projects

[x] Constant propagation · container taint · key-sensitive map tracking

[x] inheritance across rescans, bulk , flow-content filter, history

[x] Per-project exclusions, report templates, scope/exclusion/applied-rule appendices

[x] MCP server — AI coding agents dri: scan, e, explain, and SAST→dynamic probe/ loop (pip install "cpguard[mcp]", cpguard-mcp)

[ ] Framework-aware entry points (Spring, JPA) · stronger sanitizer recognition

💛 Support

CPGuard is de in the open by one person. If it is useful to you, you can support
its continued de on Fairy @cp-guard.

📄 License

Apache License 2.0. Free to use, modify and redistribute, commercially included, provided the notice and license are preserved. Includes an express patent grant.

Bundled third-party font: NanumGothic (c) NHN Corporation, under the SIL Open Font License 1.1. It ships with the package so Korean reports render on servers without Korean fonts installed.

项目信息

开发语言：Python

Star 数：24

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Open-source CPG-based interprocedural taint analysis + LLM triage, with a Ghidra-style audit workbench. Runs fully offline.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。