chainwall 0.1.0 → 2.1.0

package/README.md

@@ -1,141 +1,420 @@
 <div align="center">
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset=".github/images/logo-dark.svg">
-  <source media="(prefers-color-scheme: light)" srcset=".github/images/logo-light.svg">
-  <img alt="ChainWall" src=".github/images/logo-light.svg" width="480">
-</picture>
+<img src=".github/images/banner.png" width="700" alt="CHAINWALL">
 
 <br><br>
 
 [![CI](https://github.com/consulalialpric/chainwall/actions/workflows/tests.yml/badge.svg)](https://github.com/consulalialpric/chainwall/actions/workflows/tests.yml)
 [![npm version](https://img.shields.io/npm/v/chainwall.svg)](https://www.npmjs.com/package/chainwall)
+[![npm downloads](https://img.shields.io/npm/dm/chainwall.svg)](https://www.npmjs.com/package/chainwall)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-520_passing-brightgreen?logo=vitest&logoColor=white)](#testing)
+[![Tests](https://img.shields.io/badge/tests-743_passing-brightgreen?logo=vitest&logoColor=white)](#reference)
+[![GitHub stars](https://img.shields.io/github/stars/consulalialpric/chainwall?style=social)](https://github.com/consulalialpric/chainwall)
 
-**Antivirus for AI coding agents.**
+**Antivirus for AI agents.**
 
-Scans your machine, maps which AI tools can reach your secrets, and blocks threats before they happen.
+Your AI tools have access to every secret on your machine. ChainWall scans your filesystem, maps which tools can reach your credentials, and blocks threats before they happen.
+
+`178 detection patterns` · `18 AI tools audited` · `743 tests` · `<50ms hooks`
+
+</div>
+
+<p align="center">
+  <img src=".github/images/dashboard.png" width="680" alt="ChainWall Dashboard">
+</p>
+
+<div align="center">
+
+[Twitter](https://x.com/Antivirus) · [GitHub](https://github.com/consulalialpric/chainwall) · [@girlintokyo](https://x.com/girlintokyo)
 
 </div>
 
 ---
 
-## The Problem
+## Table of Contents
+
+- [Installation](#installation)
+- [The Problem](#the-problem)
+- [See It in Action](#see-it-in-action)
+- [What It Does](#what-it-does)
+- [Detection Patterns](#detection-patterns)
+- [Supported AI Tools](#supported-ai-tools)
+- [Architecture](#architecture)
+- [Reference](#reference)
+- [License](#license)
 
-AI coding agents have broad filesystem access. They can read your AWS credentials, SSH keys, `.env` files, crypto wallets, and browser cookies — most users have no idea how exposed they are.
+---
 
-A single prompt injection, a hallucinated shell command, or a compromised MCP server turns that access into a breach. The agent doesn't need to be malicious — it just needs to be tricked.
+## Installation
 
-ChainWall closes the gap. Scan, audit, protect — in under a minute.
+### Step 1 — Install
 
-## Quick Start
+Run this once to install ChainWall globally:
 
 ```bash
 npm install -g chainwall
+```
+
+### Step 2 — Use
+
+These are the commands you'll use day-to-day:
 
+```bash
 chainwall scan           # find secrets, keys, and PII on your machine
 chainwall audit          # map which AI tools can reach those secrets
-chainwall init           # install real-time protection hooks
+chainwall init           # install real-time protection hooks (one-time setup)
 chainwall                # launch interactive dashboard
 ```
 
+> [!NOTE]
+> `chainwall scan` and `chainwall audit` are your main tools — run them anytime to check your exposure. `chainwall init` only needs to run once per project to deploy hooks. After that, just launch `chainwall` for the full dashboard.
+
+### Where to run it
+
+<table>
+<tr>
+<td width="60">
+
+<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/apple/apple-original.svg" width="36" alt="macOS">
+
+</td>
+<td>
+
+**macOS** — Open **Terminal** (built-in, found in Applications > Utilities) or [**iTerm2**](https://iterm2.com). Both work out of the box. Bash hooks and the CLI run natively.
+
+</td>
+</tr>
+<tr>
+<td>
+
+<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/linux/linux-original.svg" width="36" alt="Linux">
+
+</td>
+<td>
+
+**Linux** — Use any terminal emulator: **GNOME Terminal**, **Konsole**, **Alacritty**, **kitty**, or whatever ships with your distro. Everything runs natively.
+
+</td>
+</tr>
+<tr>
+<td>
+
+<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/windows11/windows11-original.svg" width="36" alt="Windows">
+
+</td>
+<td>
+
+**Windows** — The `chainwall` CLI (scan, audit, dashboard) works in any terminal: **PowerShell**, **Command Prompt**, or **Windows Terminal**. However, the real-time bash hooks require a Unix shell. To get full protection including hooks, use one of these:
+
+- [**WSL2**](https://learn.microsoft.com/en-us/windows/wsl/install) (recommended) — Run `wsl --install` in PowerShell. This gives you a full Linux environment inside Windows. Install Node.js inside WSL, then `npm install -g chainwall` from there.
+- [**Git Bash**](https://gitforwindows.org) — Comes bundled with Git for Windows. Provides bash and common Unix tools. Install Git for Windows, then run ChainWall from the Git Bash terminal.
+
+</td>
+</tr>
+</table>
+
 <details>
-<summary><b>Install from source (or hooks-only without Node.js)</b></summary>
+<summary><b>Install from source</b></summary>
 <br>
 
-**Full CLI:**
 ```bash
 git clone https://github.com/consulalialpric/chainwall.git
 cd chainwall && npm install && npm run build && npm link
 ```
 
-**Hooks only (bash 3.2 + jq, no Node.js):**
+</details>
+
+<details>
+<summary><b>Hooks only (no Node.js required)</b></summary>
+<br>
+
 ```bash
 git clone https://github.com/consulalialpric/chainwall.git ~/tools/chainwall
 cd your-project && ~/tools/chainwall/install.sh
 ```
 
-Pure bash, executes in under 50ms, zero network calls.
+Pure bash + jq, executes in under 50ms, zero network calls.
 
 </details>
 
-## Demo
+---
+
+## The Problem
+
+> [!WARNING]
+> **Your AI tools can read every secret on your machine right now.**
+
+AI tools have broad filesystem access — coding agents, chat assistants, automation workflows, MCP servers — they can all reach your AWS credentials, SSH keys, `.env` files, crypto wallets, and browser cookies. Most users have no idea how exposed they are.
+
+The threat isn't hypothetical. A single prompt injection buried in a dependency README. A hallucinated shell command that pipes your keys to a remote server. A compromised MCP server that exfiltrates environment variables on every call. The agent doesn't need to be malicious — it just needs to be tricked.
+
+There's no firewall between your AI tools and your secrets. No permission model. No audit trail. You're running autonomous software with the keys to your entire digital life, and hoping for the best.
+
+ChainWall closes the gap. Scan what's exposed, see which tools can reach it, and block threats before they execute — in under a minute.
+
+---
+
+## See It in Action
 
 <p align="center">
-  <a href="https://asciinema.org/a/DASHBOARD_ID">
-    <img src="https://asciinema.org/a/DASHBOARD_ID.svg" width="600" alt="ChainWall Dashboard"/>
-  </a>
+  <img src=".github/images/demo.gif" width="680" alt="ChainWall TUI Demo">
 </p>
 
-> See also: [scan demo](https://asciinema.org/a/SCAN_ID) · [audit demo](https://asciinema.org/a/AUDIT_ID)
+> [!TIP]
+> Launch the interactive dashboard with `chainwall` (no arguments). Navigate panels with `1`-`5`, toggle protection with `p`, press `?` for help.
+
+---
 
 ## What It Does
 
-1. **Scan** — finds secrets, credentials, crypto keys, and PII across your filesystem using 156 regex patterns with entropy validation
-2. **Audit** — detects 18 AI tools on your machine and cross-references their access levels against discovered secrets to build an exposure map
-3. **Protect** — real-time bash hooks intercept dangerous operations before they execute (pre-commit, pre-push, PreToolUse/PostToolUse)
+### Scan
+
+ChainWall walks your filesystem and matches every file against 178 compiled regex patterns — credentials, private keys, crypto seeds, PII, dangerous commands, supply chain attacks, and cryptojacking. Entropy validation filters out false positives so you only see real secrets. System-level scans target the specific locations where credentials actually live: `~/.aws`, `~/.ssh`, `~/.gnupg`, browser profiles, and more.
+
+<p align="center">
+  <img src=".github/images/scan.png" width="640" alt="ChainWall scan results">
+</p>
+
+### Audit
+
+The auditor detects every AI tool on your machine — 18 tools across three access levels — then cross-references each tool's filesystem reach against your discovered secrets. The result is an exposure map: which tools can read which secrets, ranked by risk. It also inspects MCP server configurations for poisoning attacks (description injection, typosquatting, rug-pull detection), VS Code extensions, CLI tools, environment variables, running cryptocurrency miners, and skill/instruction file threats.
+
+<p align="center">
+  <img src=".github/images/audit.png" width="640" alt="ChainWall audit results">
+</p>
+
+### Protect
+
+Real-time bash hooks intercept dangerous operations before they execute. Pre-commit hooks block secrets from entering your git history. Pre-push hooks catch force-pushes and branch deletions. PreToolUse and PostToolUse hooks run inline with Claude Code to block file reads and shell commands in real-time — under 50ms, every time.
+
+> [!IMPORTANT]
+> The two layers are fully independent. Bash hooks work without Node.js installed. The TypeScript CLI works without hooks being configured. Use either or both.
+
+---
+
+## Detection Patterns
+
+178 patterns across 11 categories, with entropy validation to reduce false positives.
+
+| Category | Patterns |
+|:---------|:--------:|
+| **Credentials** | 55 |
+| **Private Keys** | 5 |
+| **Crypto / Web3** | 26 |
+| **Dangerous Commands** | 26 |
+| **PII** | 15 |
+| **Supply Chain** | 16 |
+| **Prompt Injection** | 18 |
+| **Cryptojacking** | 22 |
+| **Skill File Threats** | 25 |
+| **MCP Poisoning** | 6 modules |
+| **Permissions** | 11 |
+
+> 178 compiled rules + 25 skill-file rules + 10 contextual injection patterns + 3 shell history patterns loaded separately.
+
+<details>
+<summary><b>Credentials (55)</b></summary>
+<br>
+
+**AWS:** Access Key ID, Secret Access Key, Session Token
+**Google / GCP:** API Key, Service Account Key, OAuth Client Secret
+**Azure:** Storage Account Key, AD Client Secret, Connection String
+**GitHub:** Personal Access Token, Fine-Grained Token, OAuth Access Token, App Token, App Refresh Token
+**GitLab:** Personal Access Token, Pipeline Token, Runner Token
+**Slack:** Bot/User Token, Webhook URL
+**Stripe:** Secret Key, Restricted Key, Webhook Secret
+**OpenAI / Anthropic:** OpenAI API Key, OpenAI Project Key, Anthropic API Key
+**Twilio:** API Key, Account SID
+**SendGrid:** API Key
+**Supabase:** Service Role Key, Anon Key
+**Firebase:** Server Key
+**Databricks:** Access Token
+**npm / PyPI / Docker:** npm Access Token, PyPI API Token, Docker Hub Access Token
+**JWT / Bearer:** JSON Web Token, Bearer Token
+**HashiCorp Vault:** Service Token, Batch Token
+**Datadog:** API Key
+**Mailgun:** API Key
+**Heroku:** API Key
+**Shopify:** Access Token, Custom App Token, Private App Password
+**Linear:** API Key
+**Vercel:** Access Token
+**Generic:** API Key Assignment, Password in Config, Private Key Variable
+
+</details>
+
+<details>
+<summary><b>Private Keys (5)</b></summary>
+<br>
+
+RSA Private Key, DSA Private Key, EC Private Key, OpenSSH Private Key, PGP Private Key Block
+
+</details>
+
+<details>
+<summary><b>Crypto / Web3 (26)</b></summary>
+<br>
+
+**Seed Phrases:** BIP39 12-word, BIP39 24-word
+**Private Keys:** Ethereum (keyword context), Ethereum (env var), Solana Keypair (JSON), Solana Base58, Bitcoin WIF, MetaMask Vault/Mnemonic, Hardhat/Foundry Deployment Key
+**Exchange APIs:** Binance, Coinbase, Kraken, Bybit, OKX, KuCoin, Generic Exchange
+**Infrastructure:** Alchemy, Infura, QuickNode RPC URL, Helius RPC Key
+**Wallet Files:** Seed Phrase Backup, Electrum Wallet, Trading Bot Config, Bitcoin wallet.dat, Ethereum Keystore, Solana Keypair File
+
+</details>
+
+<details>
+<summary><b>Dangerous Commands (26)</b></summary>
+<br>
+
+**Destructive:** Recursive Force Delete (`rm -rf`), Shred File, DD to Device, Filesystem Format, Direct Device Write
+**Remote Execution:** Curl Pipe to Shell, Eval from Variable, Base64 Decode Execute
+**Permissions:** World-Writable (`chmod 777`), SetUID Bit, LD_PRELOAD Injection, PATH Manipulation
+**Network:** Netcat Listener, Reverse Shell, SSH Tunnel
+**Persistence:** Crontab Modification, Systemd Service Install, Hosts File Modification, Sudoers Modification
+**Docker Escapes:** Socket Mount, Privileged Container, Host PID Namespace, Host Network, CAP_SYS_ADMIN
+**Anti-Forensics:** History Deletion, Log Tampering
+
+</details>
+
+<details>
+<summary><b>PII (15)</b></summary>
+<br>
+
+**Identity:** US Social Security Number (with AAA validation), US SSN (no dashes), US EIN/Tax ID, Passport Number, Driver License, Date of Birth
+**Financial:** Credit Card Number (Luhn validated), Bank Account Number, Routing Number, IBAN (mod-97 validated)
+**Medical (HIPAA):** Email with PII Context, Phone in PII Context, Medical Record Number, DEA Number, Medicare ID
+
+</details>
+
+<details>
+<summary><b>Supply Chain (16)</b></summary>
+<br>
+
+**Package Managers:** pip Install from URL, pip Trusted Host, npm Registry Override, Gem Install from Source, Dependency Confusion (`--extra-index-url`)
+**Lifecycle Exploits:** Package.json Lifecycle Script (network), Package.json Lifecycle Script (eval), Setup.py OS Command
+**Lock Files:** Lock File Deletion, Lock File Git Checkout
+**Dependencies:** Git Dependency with Commit Hash, Private Registry in Lockfile, NPM Scope Confusion, Native Module Prebuild Download
+**Docker:** Image Without Tag, Image from Unknown Registry
+
+</details>
+
+<details>
+<summary><b>Prompt Injection (18)</b></summary>
+<br>
+
+**Instruction Override:** Ignore Previous Instructions, Disregard Prior Instructions, Forget Instructions, New Instructions Override
+**Identity Manipulation:** Role Assumption, Authority Claim, Admin Override
+**Prompt Extraction:** System Prompt Disclosure, Prompt Fragments, Instruction Reflection
+**Jailbreaks:** DAN/Jailbreak Keywords, Do Anything Now, Hypothetical Bypass
+**Obfuscation:** Base64 Instruction, Markdown/Code Block Injection
+**Output Control:** Output Suppression, Response Formatting Attack, Output Suppression Override
+
+</details>
+
+<details>
+<summary><b>Cryptojacking (22)</b></summary>
+<br>
 
-Both layers are fully independent. Bash hooks work without Node.js. The TypeScript CLI works without hooks.
+**Mining Pools:** Stratum+TCP URL, Stratum+SSL URL, Known Pool Domains, Mining Pool Ports
+**Miner Binaries:** XMRig, Known Miners (ethminer, cgminer, bfgminer, phoenixminer, cpuminer, claymore, t-rex, lolminer, nbminer, gminer)
+**Browser Mining:** CoinHive, CryptoLoot, WebAssembly Mining Module
+**Mining Libraries:** JS Import, Python Import
+**Configuration:** Mining Algorithm in Config, Monero Wallet Address, Mining Environment Variables, Hashrate Configuration
+**Files:** XMRig Config, Mining Pools Config, Miner Config
+**Runtime:** Mining Process Launch
 
-## What It Catches
+</details>
 
-156 patterns across 8 categories, with entropy validation to reduce false positives.
+<details>
+<summary><b>Skill File Threats (25)</b></summary>
+<br>
 
-| Category | Patterns | Examples |
-|:---------|:--------:|:---------|
-| **Credentials** | 55 | AWS, GitHub, Stripe, OpenAI, Slack, GCP, Azure, Anthropic, Twilio + 20 more |
-| **Private Keys** | 5 | RSA, DSA, EC, OpenSSH, PGP private key headers |
-| **Crypto / Web3** | 26 | BIP39 seeds, ETH/SOL/BTC private keys, exchange APIs, wallet files |
-| **Dangerous Commands** | 26 | `rm -rf`, `curl\|bash`, `chmod 777`, reverse shells, Docker escapes |
-| **PII** | 15 | SSN (with AAA validation), credit cards (Luhn), medical records, IBAN, passports |
-| **Supply Chain** | 16 | Dependency confusion, lifecycle exploits, lock file deletion |
-| **Prompt Injection** | 18 | Instruction override, role confusion, jailbreaks, base64 obfuscation |
-| **Permissions** | 11 | File permission audit: SSH keys, AWS creds, GPG keyrings |
+**Shell Payloads:** Curl Pipe to Shell, Wget Pipe to Shell, Reverse Shell, Destructive rm, chmod 777
+**Data Exfiltration:** curl POST Exfiltration, Webhook Data Send, Encoded URL Exfiltration
+**Supply Chain:** pip Install from URL, npm Install from URL/Git
+**Obfuscated Payloads:** Long Hex Escape Sequence, Long Base64 String, Eval with String Concatenation
+**Hidden Instructions:** HTML Comment with Action Keywords, Unicode Bidirectional Override, Script/Iframe Tag, Zero-Width Characters
+**Credential Harvesting:** SSH Key Read, AWS Credentials Read, .env File Read, Environment Variable Dump
+**System Modification:** Shell Profile Modification, Crontab Modification, Write to /etc/
+**Security Bypass:** Security Tool Disable, SSL/TLS Verification Disable, Password-Protected Archive Extraction
 
-> 156 compiled rules + 10 contextual injection patterns + 3 shell history patterns loaded separately.
+</details>
 
 <details>
-<summary><b>More detection capabilities</b></summary>
+<summary><b>Additional detection capabilities</b></summary>
 <br>
 
+- **MCP tool poisoning detection** — description injection, typosquatting (Levenshtein distance), excessive permission combos, suspicious URLs, known CVEs (CVE-2025-68145/68143/68144), rug-pull detection via SHA-256 hash tracking
 - **Environment variable audit** — scans process.env for 33 sensitive key patterns
-- **Prompt injection scanning** — 27 patterns across 19 instruction file types (`.cursorrules`, `CLAUDE.md`, `.windsurfrules`, etc.)
-- **Entropy-based validation** — Shannon entropy filtering on tokens
+- **Entropy-based validation** — Shannon entropy filtering on tokens to reduce false positives
 - **Base64 obfuscation detection** — catches `base64 -d | bash` and encoded payloads
 - **Docker escape detection** — socket mounts, `--privileged`, host PID/network, `CAP_SYS_ADMIN`
 - **SARIF 2.1.0 export** — `chainwall scan --format sarif` for CI/CD integration
 - **Real-time watch mode** — `chainwall watch` with debounce and content-hash caching
+- **Prompt injection scanning** — 27 patterns across 19 instruction file types (`.cursorrules`, `CLAUDE.md`, `.windsurfrules`, etc.)
 
 </details>
 
-## Supported Tools
+---
+
+## Supported AI Tools
 
-ChainWall detects and audits 18 AI coding tools, grouped by filesystem access level.
+ChainWall detects and audits 18 AI tools, grouped by filesystem access level.
 
-| Access Level | Tools |
-|:-------------|:------|
-| **Full** (any file on disk) | Claude Code, Codex CLI, Aider, Trae IDE, Bolt |
-| **Workspace** (project files) | Cursor, Windsurf, Continue.dev, Gemini Code Assist, Cline, RooCode, Amazon Q, JetBrains AI, Augment, BLACKBOXAI, Qodo Gen, Kiro |
-| **Limited** (open files only) | GitHub Copilot |
+| Access | Tools |
+|:-------|:------|
+| :red_circle: **Full** (any file on disk) | Claude Code, Codex CLI, Aider, Trae IDE, Bolt |
+| :orange_circle: **Workspace** (project files) | Cursor, Windsurf, Continue.dev, Gemini Code Assist, Cline, RooCode, Amazon Q, JetBrains AI, Augment, BLACKBOXAI, Qodo Gen, Kiro |
+| :green_circle: **Limited** (open files only) | GitHub Copilot |
 
-The auditor cross-references each tool's access level against your secrets to show exactly which tools can reach which sensitive files.
+The auditor cross-references each tool's access level against your discovered secrets to show exactly which tools can reach which sensitive files. A secret inside your project directory is reachable by every workspace-level tool. A secret in `~/.aws/credentials` is only reachable by full-access tools.
 
 Instruction files are deployed to 11 tools via `chainwall init`.
 
-## Interactive TUI
+---
+
+## Architecture
+
+```mermaid
+graph TD
+    CW["<b>CHAINWALL</b>"] --> BH["<b>Bash Hooks</b><br><i>real-time, &lt;50ms</i><br>PreToolUse · PostToolUse<br>pre-commit · pre-push"]
+    CW --> CLI["<b>TypeScript CLI</b><br><i>scan / audit / TUI</i><br>178 patterns · 18 tools<br>exposure map · SARIF"]
+    CW --> MCP["<b>MCP Server</b><br><i>agent-callable</i><br>scan_file · scan_content<br>check_command · audit_status"]
+    BH --> XR["<b>Cross-Reference</b><br><b>Exposure Map</b><br><i>secrets × tool access<br>= what's actually at risk</i>"]
+    CLI --> XR
+    MCP --> XR
+```
+
+<details>
+<summary><b>Directory structure</b></summary>
+<br>
 
-Launch with `chainwall` (no arguments) for a keyboard-driven dashboard.
+```
+hooks/              Bash hooks (PreToolUse/PostToolUse, git pre-commit/pre-push)
+patterns/           YAML pattern databases (7 files)
+rules/              Instruction files for 11 AI tools
+src/
+  commands/         scan, audit, init, watch, allow handlers
+  rules/            178 patterns as pre-compiled RegExp
+  scanner/          Async filesystem walker + rule engine
+  auditor/          18-tool detector + MCP/CLI/VS Code scanner + MCP poison detector + miner detector
+  reporter/         Terminal, JSON, SARIF, audit reports
+  tui/              Interactive TUI (Ink + React)
+  mcp-server/       4-tool MCP server (stdio transport)
+test/               Vitest tests (25 files)
+tests/              Bash test suite (11 suites)
+install.sh          Universal installer
+```
 
-- **Overview** — protection status, recent activity, system summary
-- **Scan** — mode selection, grouped results, severity/category filtering, search
-- **Audit** — 7-section accordion (summary, tools, exposure, MCP, CLIs, VS Code, env), remediation actions
-- **Settings** — allowlist/blocklist/skipDirs, toggle protection, global/project scope
-- **Logs** — audit trail with severity filtering and real-time reload
+</details>
 
-Keyboard: `1`-`5` switch panels, `p` toggles protection, `?` for help, `q` to quit.
+---
 
-## Commands
+## Reference
+
+<details>
+<summary><b>All commands</b></summary>
+<br>
 
 | Command | Description |
 |:--------|:-----------|
@@ -151,6 +430,8 @@ Keyboard: `1`-`5` switch panels, `p` toggles protection, `?` for help, `q` to qu
 | `chainwall allow --rule <id>` | Disable a detection rule |
 | `chainwall mcp` | Start MCP security server (stdio transport) |
 
+</details>
+
 <details>
 <summary><b>Flags</b></summary>
 <br>
@@ -168,7 +449,9 @@ Keyboard: `1`-`5` switch panels, `p` toggles protection, `?` for help, `q` to qu
 
 </details>
 
-## Configuration
+<details>
+<summary><b>Configuration</b></summary>
+<br>
 
 ```
 ~/.llm-av/config.json        global (all projects)
@@ -193,29 +476,31 @@ Keyboard: `1`-`5` switch panels, `p` toggles protection, `?` for help, `q` to qu
 
 Blocklist always wins. `LLMAV_SKIP=1` bypasses all checks for one invocation (always logged).
 
-## How It's Different
+</details>
 
-| Feature | ChainWall | git-secrets | truffleHog | gitleaks |
-|:--------|:---------:|:-----------:|:----------:|:--------:|
-| Real-time hook blocking | Yes | No | No | No |
-| Pre-commit scanning | Yes | Yes | Yes | Yes |
-| AI tool access auditing | Yes | No | No | No |
-| MCP server detection | Yes | No | No | No |
-| Instruction file deployment | 11 tools | No | No | No |
-| Entropy validation | Yes | No | Yes | Yes |
-| PII detection | Yes | No | No | No |
-| Crypto/Web3 patterns | 26 | No | Limited | Limited |
-| SARIF export | Yes | No | Yes | Yes |
-| Interactive TUI | Yes | No | No | No |
-| Zero-dependency hooks | bash + jq | bash + git | Go binary | Go binary |
+<details>
+<summary><b>Interactive TUI</b></summary>
+<br>
 
-**git-secrets** catches secrets at commit time but has no awareness of AI tools, MCP servers, or real-time interception. **truffleHog** and **gitleaks** are excellent for scanning repos and CI pipelines but don't operate in real-time, don't audit which AI tools can reach your secrets, and don't deploy protective instruction files.
+Launch with `chainwall` (no arguments) for a full-screen keyboard-driven dashboard.
 
-ChainWall is designed specifically for the AI coding agent threat model — where the risk isn't just committing a secret, but an agent reading, exfiltrating, or acting on it.
+| Panel | What it shows |
+|:------|:-------------|
+| **Overview** | Protection status, recent activity, system summary |
+| **Scan** | Mode selection, grouped results, severity/category filtering, search |
+| **Audit** | 9-section accordion (summary, tools, exposure, MCP, CLIs, VS Code, env, MCP poisoning, cryptojacking), remediation |
+| **Settings** | Allowlist/blocklist/skipDirs, toggle protection, global/project scope |
+| **Logs** | Audit trail with severity filtering and real-time reload |
 
-## MCP Server
+Keyboard: `1`-`5` switch panels · `p` toggle protection · `?` help · `q` quit
 
-ChainWall includes an MCP server that AI agents can call for security checks:
+</details>
+
+<details>
+<summary><b>MCP Server</b></summary>
+<br>
+
+ChainWall includes an MCP server that AI agents can call directly for security checks.
 
 | Tool | Description |
 |:-----|:-----------|
@@ -226,53 +511,74 @@ ChainWall includes an MCP server that AI agents can call for security checks:
 
 Start with `chainwall mcp` or configure in Claude Desktop / Cursor settings via `chainwall init`.
 
-This is separate from the **MCP detector** — which audits MCP servers already configured on your system, analyzes their source code for risky capabilities (filesystem, exec, network), and computes risk scores.
+> [!TIP]
+> The MCP **server** (above) lets agents call ChainWall for security checks. The MCP **detector** (part of `chainwall audit`) finds MCP servers already on your system and analyzes them for risky capabilities like filesystem access, exec, and network calls. They're separate features.
+
+</details>
 
 <details>
-<summary><b>Architecture</b></summary>
+<summary><b>How ChainWall compares</b></summary>
 <br>
 
-```
-hooks/              Bash hooks (PreToolUse/PostToolUse, git pre-commit/pre-push)
-patterns/           YAML pattern databases (5 files)
-rules/              Instruction files for 11 AI tools
-src/
-  commands/         scan, audit, init, watch, allow handlers
-  rules/            156 patterns as pre-compiled RegExp
-  scanner/          Async filesystem walker + rule engine
-  auditor/          18-tool detector + MCP/CLI/VS Code scanner
-  reporter/         Terminal, JSON, SARIF, audit reports
-  tui/              Interactive TUI (Ink + React)
-  mcp-server/       4-tool MCP server (stdio transport)
-test/               Vitest tests (20 files)
-tests/              Bash test suite (11 suites)
-install.sh          Universal installer
-```
+| Feature | ChainWall | git-secrets | truffleHog | gitleaks |
+|:--------|:---------:|:-----------:|:----------:|:--------:|
+| Real-time hook blocking | :white_check_mark: | :x: | :x: | :x: |
+| Pre-commit scanning | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| AI tool access auditing | :white_check_mark: | :x: | :x: | :x: |
+| MCP server detection | :white_check_mark: | :x: | :x: | :x: |
+| MCP poisoning detection | :white_check_mark: | :x: | :x: | :x: |
+| Skill file threat scanning | :white_check_mark: | :x: | :x: | :x: |
+| Cryptojacking detection | :white_check_mark: | :x: | :x: | :x: |
+| Instruction file deployment | 11 tools | :x: | :x: | :x: |
+| Entropy validation | :white_check_mark: | :x: | :white_check_mark: | :white_check_mark: |
+| PII detection | :white_check_mark: | :x: | :x: | :x: |
+| Crypto / Web3 patterns | 26 | :x: | Limited | Limited |
+| SARIF export | :white_check_mark: | :x: | :white_check_mark: | :white_check_mark: |
+| Interactive TUI | :white_check_mark: | :x: | :x: | :x: |
+| Zero-dependency hooks | bash + jq | bash + git | Go binary | Go binary |
 
-The two layers (bash hooks + TypeScript CLI) are fully independent. Bash hooks need only bash 3.2 + jq. The CLI needs Node.js 18.17+. Use either or both.
+> [!NOTE]
+> **git-secrets**, **truffleHog**, and **gitleaks** are excellent tools for scanning repos and CI pipelines. ChainWall is designed specifically for the AI agent threat model — where the risk isn't just committing a secret, but an agent reading, exfiltrating, or acting on it in real time.
 
 </details>
 
-## Testing
+<details>
+<summary><b>Testing</b></summary>
+<br>
 
 ```bash
 ./tests/run-all.sh    # 223 bash hook tests (11 suites)
-npm test              # 297 vitest tests (20 test files)
+npm test              # 520 vitest tests (25 test files)
 ```
 
-**520 tests total**, all passing.
+**743 tests total**, all passing.
 
-## Requirements
+</details>
+
+<details>
+<summary><b>Requirements</b></summary>
+<br>
 
 | Component | Requires |
 |:----------|:---------|
 | Bash hooks | bash 3.2+, jq |
 | ChainWall CLI | Node.js 18.17+ |
 
-## Contributing
+</details>
 
-See [CONTRIBUTING.md](docs/CONTRIBUTING.md).
+---
+
+## Community & Contributing
+
+- [Open an issue](https://github.com/consulalialpric/chainwall/issues) for bugs and feature requests
+- [Start a discussion](https://github.com/consulalialpric/chainwall/discussions) for questions and ideas
+- Follow [@girlintokyo](https://x.com/girlintokyo) and [@Antivirus](https://x.com/Antivirus) on Twitter
+- See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for development guide
+
+Built by [@girlintokyo](https://x.com/girlintokyo).
+
+---
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/dist/auditor/mcp-detector.d.ts

@@ -12,6 +12,7 @@ export interface MCPServer {
 export interface MCPDetectionResult {
     servers: MCPServer[];
     configFiles: string[];
+    definitions: Map<string, Record<string, unknown>>;
 }
 export declare function detectMCPServers(): MCPDetectionResult;
 //# sourceMappingURL=mcp-detector.d.ts.map