Skip to content
Back to search

cc-artex

MCP tool server for autonomous pentesting with Claude Code. 59 tools, exploration graph, traffic proxy, and evidence capture.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sresarehumantoo--cc-artex/badge.svg)](/listings/sresarehumantoo--cc-artex)

HTML

<a href="/listings/sresarehumantoo--cc-artex"><img src="/api/listings/sresarehumantoo--cc-artex/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Homebrew** (macOS and Linux):

brew install SREsAreHumanToo/tap/cc-artex

**Pre-built binaries:** download from the [Releases](https://github.com/SREsAreHumanToo/cc-artex/releases) page. Each release includes checksums.

**From source:**

go install github.com/SREsAreHumanToo/cc-artex/cmd/cc-artex@latest

**Docker:**

docker compose up

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 408 lines
  1. <div align="center">
  2. <img src="docs/logo.svg" alt="cc-artex" width="200">
  3. </div>
  4. <div align="center">
  5. # cc-artex
  6. **Use your Claude subscription to run pentests. No API key needed.**
  7. [![CI](https://github.com/SREsAreHumanToo/cc-artex/actions/workflows/ci.yml/badge.svg)](https://github.com/SREsAreHumanToo/cc-artex/actions/workflows/ci.yml)
  8. [![Release](https://img.shields.io/github/v/release/SREsAreHumanToo/cc-artex?logo=github)](https://github.com/SREsAreHumanToo/cc-artex/releases)
  9. [![codecov](https://codecov.io/gh/SREsAreHumanToo/cc-artex/graph/badge.svg)](https://codecov.io/gh/SREsAreHumanToo/cc-artex)
  10. [![Go Report Card](https://goreportcard.com/badge/github.com/SREsAreHumanToo/cc-artex)](https://goreportcard.com/report/github.com/SREsAreHumanToo/cc-artex)
  11. [![Go Reference](https://pkg.go.dev/badge/github.com/SREsAreHumanToo/cc-artex.svg)](https://pkg.go.dev/github.com/SREsAreHumanToo/cc-artex)
  12. [![Go 1.26+](https://img.shields.io/badge/go-1.26%2B-00ADD8?logo=go&logoColor=white)](https://go.dev/dl/)
  13. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  14. [![GitHub stars](https://img.shields.io/github/stars/SREsAreHumanToo/cc-artex?style=flat&logo=github)](https://github.com/SREsAreHumanToo/cc-artex/stargazers)
  15. </div>
  16. cc-artex is an MCP tool server that turns [ARTEX](https://github.com/Autumn-27/artex)'s autonomous pentest model into tools Claude Code calls through your existing Claude subscription. ARTEX's asset graph, exploration tracking, finding management, coverage recording, traffic capture, and report generation, exposed as 59 MCP tools. No separate LLM API key, no token budget, no agent loop of its own.
  17. You bring the brain. cc-artex brings the hands.
  18. <p align="center">
  19. <img src="docs/demo.gif" alt="cc-artex demo" width="720">
  20. </p>
  21. > **Authorized use only.** This is an offensive security tool, for penetration
  22. > testing, red teaming, CTFs and lab work. Use it only against systems you own
  23. > or have explicit permission to test.
  24. ## How it works
  25. <div align="center">
  26. <img src="docs/architecture.svg" alt="cc-artex architecture" width="800">
  27. </div>
  28. Claude Code decides what to test, what tools to call, and in what order. cc-artex executes the calls: inserting assets, tracking the exploration graph, recording findings and credentials, logging coverage, and capturing HTTP traffic through its built-in recording proxy. The exploration graph keeps Claude oriented across long engagements so it doesn't repeat work or lose context.
  29. ### What a session looks like
  30. ```
  31. $ claude
  32. > Pentest example.com, starting with reconnaissance.
  33. Claude calls: graph_overview → set_goals → insert_assets (domain: example.com)
  34. → add_intent (enumerate subdomains) → record_fact (found: api.example.com)
  35. → insert_assets (subdomain: api.example.com, service: https/443)
  36. → add_intent (test api.example.com for auth bypass)
  37. → traffic_hosts → traffic_search (host: api.example.com)
  38. → traffic_get (inspect the auth request)
  39. → traffic_replay (replay with modified auth header)
  40. → record_coverage (api /admin, idor, no_issue_found)
  41. → report_finding (severity: high, broken access control on /api/v2/users)
  42. → prove_goal (evidence: finding #1) → generate_report
  43. ```
  44. Each tool call updates the exploration graph. Claude sees where it has been, what it found, and what it planned next. If you stop and resume hours later, `graph_overview` brings it back up to speed.
  45. ## Why this exists
  46. ARTEX is a capable pentest framework with its own LLM agent loop. That agent loop needs an API key, a token budget, and careful management. If you already pay for Claude, that is a second brain doing the same job.
  47. cc-artex removes the agent loop entirely and exposes the data layer as MCP tools. Claude Code becomes the agent. You get:
  48. - **No API cost.** Your Claude subscription covers it. No token counting, no surprise bills.
  49. - **Claude's full reasoning.** Not a constrained agent loop, but Claude's complete context window and tool-use capability driving the engagement.
  50. - **Your judgment in the loop.** Claude proposes, you approve. The exploration graph means you can review its plan, steer it, and pick up where it left off.
  51. ## Install
  52. **Homebrew** (macOS and Linux):
  53. ```sh
  54. brew install SREsAreHumanToo/tap/cc-artex
  55. ```
  56. **Pre-built binaries:** download from the [Releases](https://github.com/SREsAreHumanToo/cc-artex/releases) page. Each release includes checksums.
  57. **From source:**
  58. ```sh
  59. go install github.com/SREsAreHumanToo/cc-artex/cmd/cc-artex@latest
  60. ```
  61. **Docker:**
  62. ```sh
  63. docker compose up
  64. ```
  65. ## Quick start
  66. **Prerequisites:** PostgreSQL, Go 1.26+
  67. ```sh
  68. # Create the database and initialize an engagement
  69. createdb ccartex
  70. cc-artex init --pg "postgres://localhost/ccartex" --goal "Pentest example.com"
  71. ```
  72. The init command creates the schema, sets up the engagement, generates a CA certificate for HTTPS interception, and prints trust instructions for your OS. Add the printed MCP config to your Claude Code config (`~/.claude.json` or project `.mcp.json`):
  73. ```json
  74. {
  75. "mcpServers": {
  76. "cc-artex": {
  77. "command": "cc-artex",
  78. "args": ["serve", "--stdio", "--pg", "postgres://localhost/ccartex", "--proxy", ":8788"]
  79. }
  80. }
  81. }
  82. ```
  83. The `--proxy` flag starts a recording MITM proxy alongside the MCP server. Point your tools at the proxy address (e.g., `http://localhost:8788`) to capture and analyze traffic. Without `--proxy`, the traffic tools are not registered and cc-artex runs as a pure data server.
  84. Then start Claude Code. The tools appear automatically. Ask Claude to "pentest example.com" and watch it work.
  85. For Cursor, Cline, Windsurf, Zed, and other MCP clients, see [MCP Client Configuration](docs/MCP_CLIENTS.md).
  86. ## Docker quick start
  87. **Prerequisites:** Docker and Docker Compose
  88. ```sh
  89. docker compose up
  90. ```
  91. This starts PostgreSQL and cc-artex together. On first run it automatically creates the database schema and a default engagement. The MCP server listens on `localhost:9400` and the recording proxy on `localhost:8788`.
  92. To set a specific engagement goal:
  93. ```sh
  94. CC_ARTEX_GOAL="Pentest example.com" docker compose up
  95. ```
  96. Add this to your Claude Code MCP config (`~/.claude.json` or project `.mcp.json`) to connect over HTTP:
  97. ```json
  98. {
  99. "mcpServers": {
  100. "cc-artex": {
  101. "type": "sse",
  102. "url": "http://localhost:9400/sse"
  103. }
  104. }
  105. }
  106. ```
  107. Or use stdio transport through Docker:
  108. ```json
  109. {
  110. "mcpServers": {
  111. "cc-artex": {
  112. "command": "docker",
  113. "args": [
  114. "compose", "exec", "-T", "cc-artex",
  115. "/app/cc-artex", "serve", "--stdio",
  116. "--pg", "postgres://ccartex:ccartex@postgres:5432/ccartex?sslmode=disable",
  117. "--data", "/app/data", "--proxy", ":8788"
  118. ]
  119. }
  120. }
  121. }
  122. ```
  123. Point your testing tools at `http://localhost:8788` to capture traffic through the recording proxy.
  124. ## Tool catalog
  125. 59 MCP tools across ten categories. Claude calls these automatically based on what the engagement needs.
  126. For detailed parameter documentation, see [Tool Reference](docs/TOOLS.md).
  127. <details open>
  128. <summary><strong>Exploration graph</strong></summary>
  129. | Tool | What it does |
  130. |------|-------------|
  131. | `graph_overview` | Situational summary: asset counts, goals, hints, frontier, findings, coverage |
  132. | `add_intent` | Plan a next step (queued for execution) |
  133. | `start_intent` | Move a queued intent to in-progress |
  134. | `complete_intent` | Mark a running intent as done with a result summary |
  135. | `cancel_intent` | Cancel an intent that is no longer needed |
  136. | `record_fact` | Record a discovery or observation linked to an intent |
  137. | `list_facts` | Page through exploration facts, newest first |
  138. | `node_detail` | Inspect a specific graph node by ID |
  139. | `add_hint` | Attach a strategic hint for the planner |
  140. | `set_goals` | Define or update engagement goals |
  141. | `set_constraints` | Add allow/deny operation constraints |
  142. | `prove_goal` | Link evidence to a goal and mark it proved |
  143. </details>
  144. <details>
  145. <summary><strong>Assets and scope</strong></summary>
  146. | Tool | What it does |
  147. |------|-------------|
  148. | `insert_assets` | Add domains, IPs, services, endpoints, or apps in bulk |
  149. | `list_assets` | Query assets by type, DSL filter, or ID |
  150. | `list_companies` | List tracked companies and their asset scopes |
  151. | `add_company_scope` | Add scope rules (domains, CIDRs) to a company |
  152. | `add_task_scope` | Add in-scope markers for the current task |
  153. | `list_untested_assets` | Find assets with no coverage records |
  154. | `check_scope` | Check whether a target is within scope rules |
  155. | `record_coverage` | Record what was tested, the outcome, and evidence |
  156. </details>
  157. <details>
  158. <summary><strong>Findings</strong></summary>
  159. | Tool | What it does |
  160. |------|-------------|
  161. | `report_finding` | Report a vulnerability with severity, evidence, and affected assets |
  162. | `list_findings` | List findings for the current engagement |
  163. | `bind_finding_traffic` | Link a finding to captured traffic exchanges |
  164. | `merge_findings` | Merge duplicate findings into one |
  165. | `dismiss_finding` | Mark a finding as dismissed (false positive) |
  166. </details>
  167. <details>
  168. <summary><strong>Credentials</strong></summary>
  169. | Tool | What it does |
  170. |------|-------------|
  171. | `save_task_credential` | Store a discovered credential for the current task |
  172. | `list_task_credentials` | List stored credentials |
  173. </details>
  174. <details>
  175. <summary><strong>Evidence</strong></summary>
  176. | Tool | What it does |
  177. |------|-------------|
  178. | `save_evidence` | Store a proof-of-concept artifact (file, screenshot, or text) |
  179. | `list_evidence` | List evidence items, optionally filtered by finding |
  180. | `get_evidence` | Retrieve stored evidence content by ID |
  181. | `capture_command_output` | Run a command and save its output as evidence |
  182. </details>
  183. <details>
  184. <summary><strong>Enrichment and ingestion</strong></summary>
  185. | Tool | What it does |
  186. |------|-------------|
  187. | `enrich_domain` | DNS enrichment: A/AAAA/CNAME/MX/NS/TXT records and reverse DNS |
  188. | `enrich_ip` | Reverse DNS on an IP address |
  189. | `enrich_service` | Probe an HTTP(S) service for headers, redirects, and fingerprints |
  190. | `ingest_scanner_output` | Parse and import output from nmap, nuclei, httpx, or ffuf |
  191. | `ingest_masscan` | Parse masscan XML or JSON and import hosts and open ports |
  192. </details>
  193. <details>
  194. <summary><strong>Engagement management</strong></summary>
  195. | Tool | What it does |
  196. |------|-------------|
  197. | `create_engagement` | Create a new pentest engagement (task + exploration graph) |
  198. | `list_engagements` | List all engagements with summary stats |
  199. | `switch_engagement` | Change the active engagement without restarting |
  200. | `update_engagement` | Update the current engagement's goal or description |
  201. | `delete_engagement` | Permanently delete an engagement and all its data |
  202. | `engagement_status` | Get goal, status, finding count, and coverage summary |
  203. | `engagement_activity` | Recent activity timeline: findings, assets, graph nodes |
  204. | `goal_met` | Mark the entire engagement as complete |
  205. | `list_coverage_gaps` | Identify untested assets, unproven goals, and missing enrichment |
  206. </details>
  207. <details>
  208. <summary><strong>Activity</strong></summary>
  209. | Tool | What it does |
  210. |------|-------------|
  211. | `list_activity` | List recent activity log entries for the engagement |
  212. | `log_activity` | Record a manual activity entry |
  213. </details>
  214. <details>
  215. <summary><strong>Reporting and export</strong></summary>
  216. | Tool | What it does |
  217. |------|-------------|
  218. | `generate_report` | Generate a Markdown penetration test report from the current engagement |
  219. | `export_engagement` | Export an engagement to a portable JSON archive |
  220. | `import_engagement` | Import an engagement from a JSON archive |
  221. </details>
  222. <details>
  223. <summary><strong>Traffic capture</strong> (requires <code>--proxy</code> on <code>serve</code>)</summary>
  224. Point your testing tools at the proxy to capture requests.
  225. | Tool | What it does |
  226. |------|-------------|
  227. | `traffic_search` | Search captured exchanges by host, URL, or body content |
  228. | `traffic_get` | Read the full request and response of a captured exchange |
  229. | `traffic_blob` | Page through oversized bodies by blob hash |
  230. | `traffic_messages` | List WebSocket or SSE messages of a captured stream |
  231. | `traffic_replay` | Replay a captured request with optional modifications |
  232. | `traffic_hosts` | List all recorded target hosts with exchange counts |
  233. | `traffic_har_export` | Export captured traffic as a HAR 1.2 JSON document |
  234. | `traffic_stats` | Aggregate statistics: hosts, status codes, methods, response sizes |
  235. | `traffic_timeline` | Traffic activity over time, bucketed by minute, hour, or day |
  236. </details>
  237. ## Architecture
  238. ```
  239. cc-artex/
  240. ├── cmd/cc-artex/ CLI entrypoint: serve, init, version
  241. ├── store/ PostgreSQL data layer (assets, graph, findings, credentials, coverage)
  242. ├── mcpserver/ MCP protocol server (stdio and HTTP transports)
  243. ├── tools/ Tool implementations registered with the MCP server
  244. ├── config/ Configuration loading and engagement state (.cc-artex.json)
  245. ├── traffic/ Recording MITM proxy, SOCKS5, replay, HAR export, rewrite engine
  246. │ ├── rewrite/ Rule-based request/response rewriting
  247. │ └── hookvm/ Sandboxed expression evaluator for rewrite hooks
  248. ├── evidence/ Evidence capture and storage
  249. ├── report/ Markdown report generation with quality analysis
  250. └── egress/ Rate-limiting governor for outbound requests
  251. ```
  252. The server speaks [MCP](https://modelcontextprotocol.io/) over stdio (for Claude Code) or HTTP (for other clients). All state lives in PostgreSQL. The engagement config (`.cc-artex.json`) tracks the current task and exploration IDs so the server knows which engagement to serve.
  253. ## Why cc-artex?
  254. - **Your Claude subscription IS the AI engine.** No API key management, no token budgets, no surprise bills. If you have Claude, you have everything you need.
  255. - **The exploration graph means Claude never loses context.** Every recon result, every tested endpoint, every credential, every planned next step is tracked in a persistent graph. Resume hours later and `graph_overview` brings Claude back up to speed.
  256. - **59 tools covering the full pentest lifecycle.** Asset discovery, scope management, exploration planning, traffic capture, evidence capture, credential storage, finding management, coverage tracking, and report generation.
  257. - **Works with any MCP client.** Claude Code, Cline, Cursor, or anything else that speaks the [Model Context Protocol](https://modelcontextprotocol.io/).
  258. - **One command to get started.** `docker compose up` or install the binary and run `cc-artex init`.
  259. ## cc-artex vs alternatives
  260. | | cc-artex | PentestGPT | HexStrike AI | Pentest-AI |
  261. |---|----------|-----------|-------------|-----------|
  262. | **State management** | Exploration graph (persistent, resumable) | Stateless / limited context | None | None |
  263. | **MCP native** | Yes (59 tools) | No (agent framework) | Yes (150+ tools) | Yes (205 tools) |
  264. | **Evidence chains** | Yes (findings linked to assets, coverage, traffic) | No | No | No |
  265. | **Traffic capture** | Built-in recording proxy with replay | No | No | No |
  266. | **Multi-client support** | Any MCP client (Claude Code, Cline, Cursor) | Own interface | Claude Code | Claude Code |
  267. | **License** | MIT | Research | Unknown | Unknown |
  268. cc-artex's differentiator is not tool count. It is the exploration graph and evidence chain model: every finding traces back to the asset, the coverage record, and the captured traffic that produced it.
  269. ## cc-artex vs ARTEX
  270. | | ARTEX | cc-artex |
  271. |---|-------|----------|
  272. | LLM | Built-in agent loop (needs API key) | None. Claude Code is the LLM. |
  273. | Interface | Autonomous agent | MCP tool server |
  274. | Cost | API usage (per token) | Your Claude subscription |
  275. | Asset graph | Yes | Same model, same schema |
  276. | Exploration tracking | Yes | Same model |
  277. | Findings | Yes | Same model |
  278. | Human oversight | Watch the agent run | You steer Claude directly |
  279. ## cc-artex vs manual pentesting
  280. A pentest has a lot of bookkeeping: what you have tested, what you found, what is left, which credentials go where. That bookkeeping is what cc-artex handles. Claude does the reasoning and tool selection; you do the judgment calls; cc-artex keeps the graph, the findings, and the coverage ledger so nothing falls through the cracks.
  281. ## Configuration
  282. cc-artex reads its PostgreSQL connection string from `--pg` or the `CC_ARTEX_PG` environment variable. The engagement state lives in `.cc-artex.json` in the data directory (`--data`, defaults to `.`). Config files can be JSON or TOML (the file extension determines the parser).
  283. ```sh
  284. # Serve over stdio (Claude Code)
  285. cc-artex serve --stdio --pg "postgres://localhost/ccartex"
  286. # Serve with the recording proxy
  287. cc-artex serve --stdio --pg "postgres://localhost/ccartex" --proxy :8788
  288. # Serve over HTTP (other clients)
  289. cc-artex serve --listen localhost:9400 --pg "postgres://localhost/ccartex"
  290. # Start a new engagement
  291. cc-artex init --pg "postgres://localhost/ccartex" --goal "Bug bounty: corp.example.com"
  292. ```
  293. When `--proxy` is set, cc-artex starts a recording MITM proxy on the given address. Configure your HTTP client or browser to use it, and the proxy captures every request and response for analysis through the traffic tools. The `init` command generates a CA certificate (at `traffic/_ca/mitmproxy-ca-cert.pem`) and prints OS-specific trust instructions so the proxy can intercept HTTPS.
  294. ## Examples
  295. See [docs/EXAMPLE_WALKTHROUGH.md](docs/EXAMPLE_WALKTHROUGH.md) for a complete
  296. engagement walkthrough showing every phase of a pentest session: reconnaissance,
  297. service enumeration, vulnerability testing, and report generation.
  298. ## Get help
  299. - [GitHub Issues](https://github.com/SREsAreHumanToo/cc-artex/issues) for bugs and feature requests
  300. - [GitHub Discussions](https://github.com/SREsAreHumanToo/cc-artex/discussions) for questions and ideas
  301. - [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions and how to add a tool
  302. ## License
  303. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.