# ARGUS

**Autonomous Repository Guardian and Unified Scanner**

> *"A hundred eyes on your codebase."*

An MCP server that gives any AI agent complete situational awareness of a codebase — security, quality, architecture, type safety, git history, and dead code — with **zero infrastructure**.

No server. No database. No CI plugin. No API keys. No data leaves your machine.

```bash
npx @cerionautomation/argus
```

---

## Why this exists

Ask an AI assistant "is my codebase secure?" and it guesses, because it can only see the file you pasted. It cannot see the other 400 files, run your tests, or check your git history.

ARGUS fixes that. Connect it as an MCP server and the agent gets 24 tools that read the whole repository, score it across 10 dimensions, and return structured JSON it can act on.

---

## ARGUS vs SonarQube

| | **ARGUS** | **SonarQube** |
|---|---|---|
| **Setup** | `npx @cerionautomation/argus` | Server + PostgreSQL + CI plugin + admin account |
| **Infrastructure** | None | Dedicated host, DB, JVM |
| **Cost** | Free, MIT | £15k–£150k/year enterprise |
| **Consumer** | AI agents (structured JSON) | Humans (HTML dashboard) |
| **Scan speed** | 68ms security scan on 99k lines | Minutes; full analysis 10–30 min |
| **Autonomous fixing** | Yes — self-healing loop | No |
| **False-positive transparency** | `critique_report` shows every rejection + reason | Manual triage in the UI |
| **Git churn hotspots** | Built in | Requires plugin/commercial edition |
| **Dead export detection** | Built in | Limited |
| **RAG code retrieval** | Built in (local BM25) | Not available |
| **Privacy** | 100% local | Server-side, often cloud |
| **Offline** | Works | Needs the server |

**Where SonarQube still wins:** 30+ language support (ARGUS focuses on TS/JS/Python/Go), decades of rule tuning, compliance certifications, and multi-team dashboards with historical trend reporting. ARGUS is not trying to replace an enterprise quality-gate deployment — it replaces the *feedback loop* between an AI agent and your code.

---

## Accuracy: measured, not claimed

Most scanners drown you in false positives. ARGUS validates every finding against its own evidence and rejects the ones that don't hold up.

Real result on a 99,681-line Next.js production codebase:

| Detector generation | Findings | True positives | Precision |
|---|---|---|---|
| Naive regex (v0) | 7 | 3 | **43%** |
| Multi-gate + semantic critique (v1) | 3 | 3 | **100%** |

The four eliminated false positives were:
- `"select your dates"` in **FAQ prose** flagged as SQL injection
- `select=accessToken` in a **REST URL** flagged as SQL injection
- A `console.log` flagged as a hardcoded credential *(correctly reclassified as secret-logging)*

Every rejection is inspectable via `critique_report`.

### How the accuracy works

**1. Multi-gate detection.** A SQL injection finding requires *three* independent gates:
- A well-formed SQL statement (`SELECT … FROM`, not the word "select")
- A query executor within 2 lines (`.query(`, `$queryRaw`, `knex.`)
- Not a URL or REST query string

**2. Entropy checks on secrets.** A credential must have a known key prefix (`sk-`, `ghp_`, `AKIA`, `AIza`) or genuine entropy — mixed case, digits, 20+ chars. Interpolated values, env references, and type declarations are excluded.

**3. Semantic critique.** Each surviving finding is re-examined against its own captured evidence. If the evidence contradicts the claim, it is rejected with a stated reason.

**4. Honest confidence.** The confidence number is the share of findings marked `confirmed` rather than `possible` — not a cosmetic 100%.

---

## Tools (24)

**Diagnosis**
- `full_diagnose` — everything at once: score, findings, hotspots, dead code, types
- `quantum_score` — 10-dimension weighted grade (S/A/B/C/D/F), reproducible
- `swarm_intel` — all scanners in parallel + critique loop
- `cheat_sheet` — ~150 token repo orientation for an agent

**Security**
- `security_scan` — secrets, SQLi, XSS, path traversal, weak crypto, CORS, open redirect, prototype pollution, TLS
- `standards_check` — OWASP Top 10, SOLID, 12-Factor, Clean Architecture
- `dependency_risk` — risky packages, wildcard versions, missing lockfile

**Quality**
- `code_quality` — empty catch, console.log, `@ts-ignore`, `any`, oversized files
- `type_coverage` — TypeScript strictness score
- `memory_scan` — listener leaks, missing `useEffect` cleanup, timer leaks
- `test_coverage` — ratio, assertion-free tests, skipped tests
- `dead_exports` — exported symbols nothing imports

**Git intelligence**
- `git_hotspots` — files with highest 90-day churn (churn correlates with bugs)

**RAG grounding**
- `rag_retrieve` — BM25 code retrieval, local, zero API calls
- `ground_finding` — full enclosing function + every caller of a symbol
- `critique_report` — every rejected false positive with its reason

**Action**
- `auto_diagnose` — self-healing loop: diagnose → fix → re-score → iterate
- `verify_all` — build, lint, test with captured output
- `risk_assess` — 4-dimension risk → Full Autonomy / Mixed / Structured mode
- `gap_analysis` — missing CI, linter, README, tsconfig
- `search` — ripgrep-powered, 32× faster than grep
- `think` — structured chain-of-thought scaffold
- `memory_set` / `memory_get` — cross-session persistence

**3 prompts:** `deep_audit`, `production_gate`, `debug_root_cause`
**3 resources:** `argus://{path}/health`, `/summary`, `/hotspots`

---

## Install

**Claude Code**

```bash
claude mcp add argus -- npx -y @cerionautomation/argus
```

**Claude Desktop** — add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "argus": {
      "command": "npx",
      "args": ["-y", "@cerionautomation/argus"]
    }
  }
}
```

**From source**

```bash
git clone https://github.com/CerisonAutomation/argus-mcp
cd argus-mcp && npm install && npm run build
```

---

## Engineering

- **Zero runtime dependencies** beyond the MCP SDK and Zod
- **Circuit breakers** on every scanner — an agent never hangs
- **Memory-safe walker** — 30MB total / 500KB per file caps, depth-limited
- **Sanitised exec** — `execFileSync` with argument arrays, never `shell: true`
- **Strict TypeScript** — `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`
- **MCP Spec 2025-06-18** — tool annotations, structured content, output schemas

---

## Benchmarks

Measured on a 99,681-line / 631-file Next.js + TypeScript production codebase:

| Tool | Time |
|---|---|
| `cheat_sheet` | 146ms |
| `security_scan` | 68ms |
| `quantum_score` | 189ms |
| `git_hotspots` | 24ms |
| `rag_retrieve` | 111ms |
| `dead_exports` | 286ms |

---

## Licence

MIT © Cerison Brown

Built by [Cerison Brown](mailto:cerisonbrown@gmail.com) — SDET | QA Automation Engineer | AI Workflow & Systems Automation Engineer