diff --git a/docs/01-quickstart.md b/docs/01-quickstart.md new file mode 100644 index 0000000..efb47a0 --- /dev/null +++ b/docs/01-quickstart.md @@ -0,0 +1,37 @@ +# 01 — AgentShield Quickstart + +**AgentShield (`@ritualdev-lab/agentshield` v0.2.2)** is an enterprise-grade, zero-leak secret redactor, hardware-sealed audit ledger, and OS-level execution sandbox for autonomous AI coding agents (Claude Code, Cursor, Windsurf, Antigravity). + +## 1. Run the 10-Second Interactive Demo +```bash +npx @ritualdev-lab/agentshield demo +``` + +## 2. Diagnose Your Host Sandbox & Crypto Capabilities +Verify Linux Landlock LSM / Bubblewrap / AppArmor userns, macOS Seatbelt / Keychain, Windows DPAPI, and Ed25519 signing readiness: +```bash +npx @ritualdev-lab/agentshield doctor +``` + +## 3. Protect Your Workspace & Git Commits +```bash +# Install automatic git pre-commit secret shield +npx @ritualdev-lab/agentshield hook install + +# Configure Claude Code PreToolUse hook +npx @ritualdev-lab/agentshield init-claude + +# Configure Cursor / Windsurf workspace rules +npx @ritualdev-lab/agentshield init-cursor +``` + +## 4. Sandbox & Redact Agent Commands +```bash +npx @ritualdev-lab/agentshield exec "npm test" --kernel +``` + +## Next Steps +- [02 — Architecture](02-architecture.md) +- [03 — Configuration & CLI Reference](03-configuration-and-cli.md) +- [04 — Integrations & MCP Wrapping](04-integrations-and-mcp.md) +- [05 — Enterprise VPC & Security](05-enterprise-vpc-and-security.md) diff --git a/docs/02-architecture.md b/docs/02-architecture.md new file mode 100644 index 0000000..8665bdb --- /dev/null +++ b/docs/02-architecture.md @@ -0,0 +1,18 @@ +# 02 — AgentShield Architecture + +AgentShield defends autonomous coding sessions across four deterministic, sub-millisecond defense layers: + +```mermaid +flowchart LR + Agent["AI Agent (Claude Code / Cursor / Windsurf)"] --> CLI["AgentShield CLI / MCP Wrapper"] + CLI --> Redactor["Shared Core Redactor (Linear-Time DFA + H>4.5 Entropy + 25ms Breaker)"] + CLI --> Sandbox["OS Kernel Sandbox (Landlock / bwrap / Seatbelt / AST Gate)"] + CLI --> Ledger["Ed25519 Hardware-Sealed Audit Ledger (Keychain / Secret Service / DPAPI)"] + Ledger --> SIEM["CEF / Syslog / Splunk / Datadog SIEM"] +``` + +## Defense Layers +1. **Linear-Time Core Redactor (`@ritualdev-lab/agentshield/core-redactor`)**: Zero-dependency DFA-safe regex catalog + Shannon entropy (`H > 4.5`) + hard `25ms` per-chunk circuit-breaker and unified staged-diff AST redaction. +2. **Boundary-Safe Streaming Interceptor**: Handles arbitrary chunk splits, multibyte UTF-8 boundaries, and fail-closed multiline PEM private key windowing. +3. **OS Kernel & Command Sandbox**: Enforces read/write boundaries using Linux Landlock LSM + Bubblewrap (`bwrap`), macOS Seatbelt (`sandbox-exec`), or Windows AST + restricted process boundaries. +4. **Hardware-Sealed Asymmetric Audit Ledger (`src/ledger.ts` & `src/keystore.ts`)**: Signs every sequential hash-chained audit block with an Ed25519 private key sealed in the host OS keystore so compromised local processes cannot forge historical audit records. diff --git a/docs/03-configuration-and-cli.md b/docs/03-configuration-and-cli.md new file mode 100644 index 0000000..ff1b9ba --- /dev/null +++ b/docs/03-configuration-and-cli.md @@ -0,0 +1,23 @@ +# 03 — AgentShield Configuration & CLI Reference + +## Unified CLI Commands + +| Command | Description | +| :--- | :--- | +| `agentshield doctor [--json]` | Run cross-platform sandbox, kernel, and Ed25519 diagnostics. | +| `agentshield scan [--json]` | Scan files or directories for leaked secrets. | +| `agentshield redact ` | Output secret-redacted text to stdout. | +| `agentshield exec [--kernel]` | Sandbox and intercept agent shell execution. | +| `agentshield wrap ` | Transparent zero-config MCP stdio security wrapper. | +| `agentshield ledger verify [path] [--pub-key ]` | Verify Ed25519 asymmetric signatures and hash-chain integrity offline. | +| `agentshield db-proxy [args...]` | Unified platform bridge to `@ritualdev-lab/dbshield`. | +| `agentshield compact [args...]` | Unified platform bridge to `@ritualdev-lab/skillprism`. | +| `agentshield ci [--base origin/main] [--sarif out.sarif]` | CI/CD pull request leak gate with OASIS SARIF 2.1.0 output. | + +## Environment Variables + +| Variable | Purpose | +| :--- | :--- | +| `AGENTSHIELD_AIR_GAPPED=1` | Strict zero-egress air-gapped execution mode. | +| `AGENTSHIELD_KEYSTORE` | Override Ed25519 keystore backend (`macos-keychain`, `linux-keyring`, `windows-dpapi`, `file-0600`, `memory`). | +| `AGENTSHIELD_LEDGER_KEY` | Optional supplemental HMAC chain salt for legacy compatibility. | diff --git a/docs/04-integrations-and-mcp.md b/docs/04-integrations-and-mcp.md new file mode 100644 index 0000000..e84c733 --- /dev/null +++ b/docs/04-integrations-and-mcp.md @@ -0,0 +1,27 @@ +# 04 — Integrations & MCP Wrapping + +## Wrapping Any MCP Server +Wrap any third-party MCP server in Claude Desktop, Cursor, or Windsurf without modifying upstream code: +```json +{ + "mcpServers": { + "github-protected": { + "command": "npx", + "args": ["-y", "@ritualdev-lab/agentshield", "wrap", "npx", "-y", "@modelcontextprotocol/server-github"] + } + } +} +``` + +## Importing the Shared Core Redactor SDK +```ts +import { redactText, redactStagedDiff } from "@ritualdev-lab/agentshield/core-redactor"; + +const result = redactText(agentOutput, { maxScanMs: 25, entropyThreshold: 4.5 }); +``` + +## Python SDK (`agentshield-python` v0.2.2) +Python teams can install the synchronized `agentshield-python` package to protect LangChain, CrewAI, and AutoGen tool pipelines with matching redaction policies. + +## GitHub Actions PR Gate +Use `RitualDev-Lab/AgentShield` directly in CI (`npx @ritualdev-lab/agentshield ci --base origin/main --sarif agentshield.sarif`) to block leaked credentials before merge. diff --git a/docs/05-enterprise-vpc-and-security.md b/docs/05-enterprise-vpc-and-security.md new file mode 100644 index 0000000..eb7db5f --- /dev/null +++ b/docs/05-enterprise-vpc-and-security.md @@ -0,0 +1,12 @@ +# 05 — Enterprise VPC & Security Controls + +## Air-Gapped Private VPC Deployment +AgentShield ships with production Helm charts and Terraform modules (AWS, Azure, GCP) maintained canonically in [`RitualDev-Lab/enterprise-governance-suite`](https://github.com/RitualDev-Lab/enterprise-governance-suite) and mirrored in [`RitualDev-Lab/agentshield-helm`](https://github.com/RitualDev-Lab/agentshield-helm): +- Zero outbound internet egress (`NetworkPolicy` restricted to RFC 1918 CIDRs). +- Non-root UID `10001`, read-only root filesystem, `cap_drop: [ALL]`, Seccomp `RuntimeDefault`. +- Self-hostable `agent-defense-hub` control plane supporting Okta OIDC / Entra SAML 2.0 SSO, 3-role RBAC (`Admin`, `Approver`, `Developer`), Ed25519 policy signing, and CEF/Splunk/Datadog SIEM forwarding. + +## Compliance Alignment & Verification +- Maps secret-prevention and audit-integrity controls to **SOC 2 CC6.1/CC6.8**, **ISO 27001 A.8.24**, and **OWASP LLM06**. +- Hardware-sealed Ed25519 audit ledgers can be verified offline by external auditors via `agentshield ledger verify --pub-key `. +- Responsible vulnerability disclosure: see [SECURITY.md](../SECURITY.md) or `security@ritualdev.in`.