archgraph 0.2.0__tar.gz

archgraph-0.2.0/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(source:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(archgraph --help:*)",
+      "WebSearch",
+      "WebFetch(domain:libclang.readthedocs.io)",
+      "WebFetch(domain:eli.thegreenplace.net)",
+      "Bash(wc -l:*)",
+      "Bash(pytest:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)"
+    ]
+  }
+}

archgraph-0.2.0/.dockerignore

@@ -0,0 +1,12 @@
+.git
+.venv
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+assets/
+docs/
+tests/
+*.md
+!README.md
+LICENSE

archgraph-0.2.0/.github/REPO_SETTINGS.md

@@ -0,0 +1,13 @@
+# GitHub Repository Settings
+
+Apply these settings manually via GitHub web UI (Settings > General):
+
+## About
+
+**Description:**
+Source code knowledge graph extraction tool. Parses 10 languages via tree-sitter, builds Neo4j graph with CFG, data flow, taint analysis, and CVE enrichment.
+
+**Website:** *(leave empty or add docs link)*
+
+**Topics:**
+`reverse-engineering` `static-analysis` `neo4j` `tree-sitter` `code-analysis` `security` `taint-analysis` `control-flow-graph` `cypher` `python`

archgraph-0.2.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Ruff
+.ruff_cache/
+
+# Neo4j data
+neo4j_data/
+
+# Tree-sitter compiled grammars
+grammars/
+
+# rlm internal docs (not part of archgraph)
+rlm-perspectives.md
+rlm_insights.md
+tools.md
+
+# Accidental pip output
+=18.1.0
+.bg-shell/

archgraph-0.2.0/CLAUDE.md

@@ -0,0 +1,66 @@
+# ArchGraph
+
+Kaynak kod graph extraction & Cypher query tool for reverse engineering.
+
+## Geliştirme Ortamı
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Testler
+
+```bash
+# Tüm testler (102 test — 98 passed, 4 skipped)
+pytest tests/ -v
+```
+
+Test dosyaları Neo4j gerektirmez. Tree-sitter ve git testleri `tmp_path` fixture ile gerçek parse/commit yapar.
+
+## Kod Kuralları
+
+- Python 3.11+, type hint zorunlu
+- Ruff formatter, line-length 100
+- Her extractor `BaseExtractor`'dan türer, `extract(repo_path, **kwargs) -> GraphData` döner
+- Extractor'lara `workers` kwarg ile parallelism geçirilir (thread-local parser)
+- Node ID formatı: `{tip}:{yol}:{isim}:{satır}` (ör. `func:src/main.c:parse_data:42`)
+- Edge'ler `(source_id, target_id, type)` tuple ile unique
+- `GraphData.deduplicate()` pipeline sonunda çağrılır
+- `GraphData.merge()` tek thread'de çağrılmalı (futures.result() sonrası)
+- Security label'lar `config.py`'deki frozenset'lerle eşleşir
+- Neo4j importta `_Node` label'ı tüm node'lara eklenir (cross-label query için)
+- Neo4j'de `_id` property unique constraint taşır
+
+## Thread Safety
+
+- `ts.Language` objeleri thread-safe → paylaşılabilir
+- `ts.Parser` objeleri thread-safe DEĞİL → `threading.local()` ile thread-başına instance
+- libclang `Index` thread-safe değil → her thread kendi `Index.create()`
+- Pipeline merge işlemleri ana thread'de yapılır
+
+## Kilit Dosyalar
+
+| Dosya | Açıklama |
+|-------|----------|
+| `archgraph/config.py` | Tüm sabitler, güvenlik pattern'leri, `ExtractConfig` dataclass |
+| `archgraph/graph/builder.py` | 9-adım pipeline orkestrasyon (parallel/sequential) |
+| `archgraph/graph/schema.py` | `Node`/`Edge` dataclass, `NodeLabel`/`EdgeType` sabitleri |
+| `archgraph/graph/neo4j_store.py` | Neo4j batch import, `_Node` label, `_id` unique |
+| `archgraph/extractors/treesitter.py` | Ana extractor, 10 dil, thread-local parser |
+| `archgraph/extractors/clang.py` | libclang deep analysis (CFG, data flow, taint) |
+| `archgraph/extractors/deep/` | Tree-sitter deep analysis (Rust, Java, Go, Kotlin, Swift) |
+| `archgraph/enrichment/cve.py` | CVE enrichment — OSV API batch query |
+| `archgraph/tool/archgraph_tool.py` | rlm-agent tool (standalone, BaseTool bağımlılığı yok) |
+
+## Dokümantasyon
+
+Detaylı dökümantasyon `docs/` altında:
+
+- `docs/ARCHITECTURE.md` — Proje yapısı, pipeline, graph schema, node/edge tipleri
+- `docs/CLI.md` — Tüm komutlar ve option'lar
+- `docs/DEEP_ANALYSIS.md` — CFG, data flow, taint, dil-bazlı pattern'ler
+- `docs/SECURITY.md` — Security labeling, CVE enrichment, örnek sorgular
+- `docs/AGENT.md` — rlm-agent entegrasyonu, API referansı
+- `docs/ROADMAP.md` — Faz 1-4 durumu

archgraph-0.2.0/Dockerfile

@@ -0,0 +1,29 @@
+# --- Stage 1: Builder ---
+FROM python:3.11-slim AS builder
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc g++ git \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /build
+COPY . .
+
+ARG INSTALL_EXTRAS=""
+RUN if [ -z "$INSTALL_EXTRAS" ]; then \
+        pip install --no-cache-dir .; \
+    else \
+        pip install --no-cache-dir ".[$INSTALL_EXTRAS]"; \
+    fi
+
+# --- Stage 2: Runtime ---
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=builder /usr/local/bin/archgraph /usr/local/bin/archgraph
+
+WORKDIR /data
+ENTRYPOINT ["archgraph"]

archgraph-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 ArchGraph Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

archgraph-0.2.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: archgraph
+Version: 0.2.0
+Summary: Security-first code intelligence for AI agents — taint analysis, CVE detection, MCP integration
+Author: ArchGraph Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,code-analysis,knowledge-graph,mcp,neo4j,security,static-analysis,taint-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.0
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: neo4j>=5.0.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: toml>=0.10.0
+Requires-Dist: tree-sitter-c>=0.23.0
+Requires-Dist: tree-sitter-cpp>=0.23.0
+Requires-Dist: tree-sitter-go>=0.23.0
+Requires-Dist: tree-sitter-java>=0.23.0
+Requires-Dist: tree-sitter-javascript>=0.23.0
+Requires-Dist: tree-sitter-rust>=0.23.0
+Requires-Dist: tree-sitter-typescript>=0.23.0
+Requires-Dist: tree-sitter>=0.24.0
+Requires-Dist: uvicorn>=0.29.0
+Provides-Extra: all
+Requires-Dist: libclang>=18.1.0; extra == 'all'
+Requires-Dist: tree-sitter-kotlin>=0.23.0; extra == 'all'
+Requires-Dist: tree-sitter-objc>=3.0.0; extra == 'all'
+Requires-Dist: tree-sitter-swift>=0.6.0; extra == 'all'
+Provides-Extra: clang
+Requires-Dist: libclang>=18.1.0; extra == 'clang'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Provides-Extra: kotlin
+Requires-Dist: tree-sitter-kotlin>=0.23.0; extra == 'kotlin'
+Provides-Extra: objc
+Requires-Dist: tree-sitter-objc>=3.0.0; extra == 'objc'
+Provides-Extra: swift
+Requires-Dist: tree-sitter-swift>=0.6.0; extra == 'swift'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/banner.svg" alt="ArchGraph" width="700"/>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"/></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"/></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Server-green.svg" alt="MCP Server"/></a>
+  <img src="https://img.shields.io/badge/tests-137%20passed-brightgreen.svg" alt="Tests"/>
+</p>
+
+<p align="center">
+  <b>Security-first code intelligence for AI agents.</b><br/>
+  Parses <b>10 languages</b>, builds a knowledge graph with <b>taint analysis</b>, <b>CVE detection</b>, and <b>clustering</b>.<br/>
+  Connect to any AI agent via <b>MCP</b> — Cursor, Claude Code, Windsurf, and more.
+</p>
+
+---
+
+## Why ArchGraph?
+
+Other tools help you *understand* code. **ArchGraph helps you *secure* it.**
+
+| | **ArchGraph** | **Code Search** | **AST Parsers** | **SAST Tools** |
+|--|---------------|-----------------|-----------------|----------------|
+| **Taint Analysis** | ✅ Input → Sink | ❌ | ❌ | ✅ |
+| **CVE Detection** | ✅ Auto via OSV | ❌ | ❌ | Partial |
+| **CFG / Data Flow** | ✅ libclang + tree-sitter | ❌ | Partial | ✅ |
+| **MCP for AI Agents** | ✅ 7 tools | ❌ | ❌ | ❌ |
+| **Functional Clustering** | ✅ Community detection | ❌ | ❌ | ❌ |
+| **Execution Tracing** | ✅ Entry → Sink flows | ❌ | ❌ | ❌ |
+| **Export (JSON/GraphML)** | ✅ | ❌ | ❌ | Partial |
+| **Local-first** | ✅ Neo4j | Varies | ✅ | Varies |
+| **License** | MIT | Varies | Varies | Often proprietary |
+
+---
+
+## Quick Start
+
+```bash
+# Install
+pip install archgraph
+
+# Extract (auto-detects languages)
+archgraph extract /path/to/repo -w 4
+
+# Query the graph
+archgraph query "MATCH (f:Function {is_input_source: true}) RETURN f.name, f.file"
+
+# Start web dashboard
+archgraph serve --port 8080
+
+# Generate HTML security report
+archgraph report /path/to/repo
+```
+
+**With Docker (Neo4j included):**
+```bash
+docker compose up -d neo4j           # password: archgraph
+archgraph extract /path/to/repo --neo4j-password archgraph
+```
+
+---
+
+## 🤖 AI Agent Integration (MCP)
+
+ArchGraph exposes 7 tools and 4 resources to any MCP-compatible agent.
+
+### Setup
+
+```bash
+# Index your repo
+archgraph extract . --include-cve --include-clustering
+
+# Start MCP server
+archgraph mcp
+```
+
+**Connect your agent:**
+
+| Agent | Command |
+|-------|---------|
+| Claude Code | `claude mcp add archgraph -- archgraph mcp` |
+| Cursor | Add to `~/.cursor/mcp.json` |
+| Windsurf | Add to MCP config |
+| OpenCode | Add to `~/.config/opencode/config.json` |
+
+### What Your Agent Gets
+
+**Tools:** `query`, `impact`, `context`, `detect_changes`, `find_vulnerabilities`, `cypher`, `stats`
+
+**Resources:** `archgraph://schema`, `archgraph://security`, `archgraph://clusters`, `archgraph://processes`
+
+### Example Conversation
+
+```
+You: "Are there any buffer overflow risks in the network code?"
+
+Agent:
+1. Queries input sources in network files
+2. Traces taint paths to dangerous sinks
+3. Reports: "Found 2 paths:
+   - net_recv() → memcpy() in src/net/handler.c (depth: 3)
+   - read_packet() → strcpy() in src/net/parser.c (depth: 4)
+   Both reach dangerous sinks without validation."
+```
+
+---
+
+## 🔒 Security Features
+
+**Automatic labeling** — Every function gets security labels:
+- `is_input_source` — reads external data (recv, read, fetch, ...)
+- `is_dangerous_sink` — dangerous operations (memcpy, exec, eval, ...)
+- `is_allocator`, `is_crypto`, `is_parser` — additional categories
+- `risk_score` — 0-100 risk score based on labels
+
+**Taint path detection:**
+```cypher
+MATCH path = (src:Function {is_input_source: true})-[:CALLS*1..8]->(sink:Function {is_dangerous_sink: true})
+RETURN src.name, sink.name, length(path) AS depth
+```
+
+**CVE enrichment:**
+```bash
+archgraph extract . --include-cve    # Queries OSV API automatically
+```
+
+---
+
+## All Commands
+
+| Command | Description |
+|---------|-------------|
+| `extract` | Extract code graph from repository |
+| `query` | Run Cypher queries against the graph |
+| `stats` | Show node/edge statistics |
+| `schema` | Show graph schema |
+| `diff` | Compare repo state vs stored graph |
+| `impact` | Blast radius analysis for a function |
+| `export` | Export to JSON, GraphML, or CSV |
+| `report` | Generate HTML security report |
+| `serve` | Start web dashboard |
+| `mcp` | Start MCP server for AI agents |
+| `skills` | Generate AI agent skill files |
+| `repos` | List indexed repositories |
+
+---
+
+## Use Cases
+
+### Security Audit
+```bash
+archgraph extract /target -l c,cpp --include-cve --include-clang
+archgraph query "MATCH path = (src:Function {is_input_source: true})-[:CALLS*1..5]->(sink:Function {is_dangerous_sink: true}) RETURN src.name, sink.name"
+```
+
+### Code Review
+```bash
+archgraph diff /path/to/repo
+archgraph impact "func:src/api.c:handle:42" --direction both
+```
+
+### Reverse Engineering
+```bash
+archgraph extract /binary/project -l c,cpp,rust --include-clang --include-deep
+archgraph query "MATCH (f:Function) WHERE f.is_exported = true RETURN f.name, f.file"
+```
+
+---
+
+## Architecture
+
+```
+                  ┌──────────────────────────────────────────────────┐
+                  │         GraphBuilder Pipeline (11 steps)         │
+                  │                                                  │
+  Local Path ─────┤  1. Tree-sitter structural extraction            │
+     or           │  2. Git history                                  │
+  GitHub URL ─────┤  3. Dependency extraction                        │──── Neo4j
+  (auto clone)    │  4. Annotation scanning                          │     Store
+                  │  5. Security labeling                            │       │
+                  │  6. Clang deep analysis (C/C++)                  │       ├── MCP Server
+                  │  7. Tree-sitter deep analysis (Rust/Java/Go/…)   │       ├── Web Dashboard
+                  │  8. Churn enrichment                             │       └── Export/Report
+                  │  9. CVE enrichment (OSV API)                     │
+                  │ 10. Clustering (community detection)             │
+                  │ 11. Process tracing (execution flows)            │
+                  └──────────────────────────────────────────────────┘
+```
+
+---
+
+## Benchmarks
+
+| Project | Language | Files | Nodes | Edges | Time |
+|---------|----------|-------|-------|-------|------|
+| [zlib](https://github.com/madler/zlib) (~50K LOC) | C | 79 | 2,389 | 3,968 | 6.6s |
+| [fastify](https://github.com/fastify/fastify) (~30K LOC) | JavaScript | 487 | 2,810 | 18,472 | 10.5s |
+| Linux `drivers/usb` (~500K LOC) | C | 892 | 62,812 | 122,746 | 12.7s |
+
+*Benchmarks: Windows 11, Python 3.13, single-threaded. Parallel mode (`-w 4`) is 2-3x faster.*
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Architecture & Schema](docs/ARCHITECTURE.md) | Graph schema, node/edge types, pipeline |
+| [CLI Reference](docs/CLI.md) | All commands and options |
+| [AI Agent Integration](docs/AGENT.md) | MCP setup, tools, examples |
+| [Security Analysis](docs/SECURITY.md) | Security labeling, Cypher queries |
+| [Deep Analysis](docs/DEEP_ANALYSIS.md) | CFG, data flow, taint tracking |
+| [Roadmap](docs/ROADMAP.md) | Development phases |
+
+---
+
+## Testing
+
+```bash
+pytest tests/ -v  # 137 passed, 22 skipped
+```
+
+No external services required. Tests use temporary directories with real tree-sitter parsing and git operations.
+
+---
+
+## License
+
+[MIT](LICENSE)