Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions docs/01-quickstart.md
Original file line number Diff line number Diff line change
@@ -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)
18 changes: 18 additions & 0 deletions docs/02-architecture.md
Original file line number Diff line number Diff line change
@@ -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.
23 changes: 23 additions & 0 deletions docs/03-configuration-and-cli.md
Original file line number Diff line number Diff line change
@@ -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 <path> [--json]` | Scan files or directories for leaked secrets. |
| `agentshield redact <path>` | Output secret-redacted text to stdout. |
| `agentshield exec <cmd> [--kernel]` | Sandbox and intercept agent shell execution. |
| `agentshield wrap <server...>` | Transparent zero-config MCP stdio security wrapper. |
| `agentshield ledger verify [path] [--pub-key <pem>]` | 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. |
27 changes: 27 additions & 0 deletions docs/04-integrations-and-mcp.md
Original file line number Diff line number Diff line change
@@ -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.
12 changes: 12 additions & 0 deletions docs/05-enterprise-vpc-and-security.md
Original file line number Diff line number Diff line change
@@ -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 <path> --pub-key <signer.pub.pem>`.
- Responsible vulnerability disclosure: see [SECURITY.md](../SECURITY.md) or `[email protected]`.
Loading