npm package: @flowguard/cli
Description: AI Agent Security — scan every tool call for secrets, PII, destructive commands, and prompt injection. Runs locally, zero dependencies, no signup required.
Author: FlowGuard
Latest version: 0.5.0

# FlowGuard

**Security for AI agents.** Scan every tool call for secrets, PII, destructive commands, and prompt injection. Runs locally with zero dependencies.

```bash
npx @flowguard/cli init
```

One command. No signup. No API key. No cloud. Instant protection for Claude Code, Cursor, Windsurf, and Codex.

---

## Why FlowGuard

AI agents execute code, read files, query databases, and send emails -- all without human review. FlowGuard sits between your AI agent and its tools, scanning every interaction in real-time.

**What happens without FlowGuard:**

- Agent leaks AWS keys in a commit
- Agent `rm -rf`s your project directory
- Malicious MCP server injects hidden instructions via tool descriptions
- Agent exfiltrates sensitive data through a compromised tool

**What happens with FlowGuard:**

- Every tool call scanned in < 1ms, locally
- Secrets, PII, and destructive commands blocked before execution
- Local dashboard shows everything your agents are doing
- Full audit trail stored in local SQLite

---

## Quick Start

```bash
# Install and protect your AI tools
npx @flowguard/cli init

# Check protection status
npx @flowguard/cli status

# Start local dashboard
npx @flowguard/cli start
```

FlowGuard auto-detects your AI tools, installs lightweight hooks, and starts protecting immediately. You'll see `[FlowGuard]` messages in your terminal on every tool call.

---

## What It Detects

| Category                  | Examples                                               | Severity     |
| ------------------------- | ------------------------------------------------------ | ------------ |
| **Secrets & Credentials** | AWS keys, API tokens, private keys, connection strings | RESTRICTED   |
| **Personal Data (PII)**   | SSN, credit cards, email, phone numbers                | RESTRICTED   |
| **Dangerous Commands**    | `rm -rf /`, `mkfs`, piped curl to shell                | CRITICAL     |
| **Prompt Injection**      | Ignore instructions, persona override, jailbreak       | CRITICAL     |
| **Hardcoded Passwords**   | Env secrets, database credentials in code              | CONFIDENTIAL |

### MCP Server Scanning

When used with the FlowGuard MCP proxy, every MCP server is scanned on first connect:

| Engine              | What It Finds                                                |
| ------------------- | ------------------------------------------------------------ |
| ESLint SAST         | Code injection, eval(), exec(), unsafe patterns              |
| Secretlint          | Hardcoded secrets in server source code                      |
| Config Scanner      | Insecure transport, excessive permissions, untrusted sources |
| Tool Poisoning      | Hidden instructions in tool descriptions (OWASP MCP #8)      |
| Tool Pinner         | Rug-pull attacks -- detects when tool definitions change     |
| Permission Analyzer | Least-privilege violations                                   |
| Dependency Scanner  | CVEs via OSV.dev -- zero binary deps                         |
| SBOM Generator      | CycloneDX SBOM + license compliance                          |

Optional subprocess scanners (if installed): Trivy, Gitleaks, Grype, Semgrep.

---

## Supported AI Tools

| Tool           | Status      | Method       |
| -------------- | ----------- | ------------ |
| Claude Code    | Supported   | Hook scripts |
| Cursor         | Supported   | Hook scripts |
| Windsurf       | Supported   | Hook scripts |
| Codex          | Coming soon | Hook scripts |
| Claude Desktop | Supported   | MCP proxy    |
| Any MCP client | Supported   | MCP proxy    |

---

## Commands

```bash
npx @flowguard/cli init       # Auto-detect tools + install hooks
npx @flowguard/cli status     # Show what's protected
npx @flowguard/cli start      # Start local dashboard (localhost:3000)
npx @flowguard/cli stop       # Stop local dashboard
npx @flowguard/cli uninstall  # Remove all hooks
```

---

## How It Works

```
Your AI Agent (Claude Code, Cursor, etc.)
       |
       v
  [FlowGuard Hook]  <-- scans every tool call in < 1ms
       |
       v
  Your tools execute normally
```

- **Everything runs locally** -- no network calls, no cloud, no telemetry
- **Regex-based scanning** -- sub-millisecond latency, zero performance impact
- **SQLite storage** -- all events logged to `~/.flowguard/flowguard.db`
- **Local dashboard** -- `npx @flowguard/cli start` opens a web UI at localhost:3000

---

## Local Dashboard

The dashboard gives you visibility into everything your AI agents are doing:

- **Data flow timeline** -- every tool call with classification labels
- **Agent discovery** -- which agents are active, what tools they use
- **Risk scoring** -- per-agent and per-session risk assessment
- **Policy violations** -- blocked actions with severity and context
- **MCP server scanner** -- vulnerability findings, OWASP MCP Top 10 coverage

---

## Configuration

```bash
# Environment variables (optional)
FLOWGUARD_API_URL    # Dashboard endpoint (default: http://localhost:3000)

# Config files (auto-created by init)
~/.flowguard/flowguard.db       # Local SQLite database
~/.flowguard/guard-rules.yaml   # Custom classification rules
~/.flowguard/policy.yaml        # Policy enforcement rules
```

### Custom Rules

Add your own detection patterns in `~/.flowguard/guard-rules.yaml`:

```yaml
rules:
  - id: internal-project-code
    pattern: "PROJ-[0-9]{4}"
    tier: INTERNAL
    label: "Internal Project Code"
```

---

## Coming Soon

- Codex support
- Team dashboard (share visibility across your team)
- Policy-as-code enforcement
- Slack/email alerting

---

## License

MIT