@goplus/agentguard 1.0.14 → 1.1.3

package/docs/cloud-connect.md

@@ -0,0 +1,73 @@
+# Connect AgentGuard OSS to AgentGuard Cloud
+
+AgentGuard is local-first. Cloud is optional and adds hosted policy, redacted audit sync, session timelines, and approval workflows.
+
+## Install and initialize
+
+```bash
+npm install -g @goplus/agentguard
+agentguard init
+```
+
+This creates `~/.agentguard/config.json`, `~/.agentguard/audit.jsonl`, and local cache paths.
+
+## Connect Cloud
+
+```bash
+AGENTGUARD_API_KEY=ag_live_xxxxx \
+  agentguard connect --url https://agentguard.gopluslabs.io
+```
+
+`connect` stores the API key locally, fetches `/api/v1/policies/effective`, and caches the policy. If Cloud is unavailable, AgentGuard keeps enforcing with cached policy or the bundled default policy.
+
+Prefer `AGENTGUARD_API_KEY` or an ignored `.env.local` file over passing secrets as CLI flags, because shell history can persist command-line arguments.
+
+## Runtime flow
+
+1. Agent host sends tool metadata to `agentguard protect`.
+2. AgentGuard evaluates locally by default.
+3. Local audit is written to `~/.agentguard/audit.jsonl`.
+4. Connected clients sync redacted audit events to `/api/v1/events/ingest`.
+5. `require_approval` creates `/api/v1/approvals` and blocks the action until reviewed.
+
+Use `AGENTGUARD_DECISION_MODE=cloud` or `agentguard protect --decision-mode cloud` only when Cloud should be authoritative for a specific hook.
+
+## Commands
+
+```bash
+agentguard status
+agentguard doctor
+agentguard scan ./skills/example
+agentguard protect --agent claude-code --action-type shell --tool-name Bash
+```
+
+For the full native API contract, see [AgentGuard Cloud Native API](cloud-native-api.md).
+
+## Live Cloud smoke test
+
+The normal test suite uses mocks and never touches Cloud. To verify a real test environment, build first and pass credentials through your shell:
+
+```bash
+npm run build
+AGENTGUARD_CLOUD_URL=https://your-agentguard-cloud.example.com \
+AGENTGUARD_API_KEY=ag_live_xxxxx \
+  npm run test:cloud-live
+```
+
+You may also keep local-only credentials in an ignored `.env.local` file:
+
+```bash
+AGENTGUARD_CLOUD_URL=https://your-agentguard-cloud.example.com
+AGENTGUARD_API_KEY=ag_live_xxxxx
+```
+
+Then run:
+
+```bash
+set -a
+. ./.env.local
+set +a
+npm run test:cloud-live
+```
+
+Do not commit `.env.local`, `.env`, `~/.agentguard/config.json`, or any real API key.

package/docs/cloud-native-api.md

@@ -0,0 +1,526 @@
+# AgentGuard Cloud Native API
+
+This document summarizes the Cloud APIs that a local/native AgentGuard runtime should use. The native client remains local-first: it enforces policy locally by default, uses Cloud for hosted policy and audit visibility, and never depends on the network to block a known-dangerous action.
+
+## Base URL and authentication
+
+Production base URL:
+
+```text
+https://agentguard.gopluslabs.io
+```
+
+All protected runtime APIs require an AgentGuard API key:
+
+```http
+X-API-Key: ag_live_xxxxx
+```
+
+`Authorization: Bearer ag_live_xxxxx` is also accepted by the Cloud proxy, but `X-API-Key` is the recommended native-client header.
+
+## Recommended native flow
+
+1. `agentguard connect` stores `cloudUrl` and `apiKey` in the local config.
+2. Fetch `GET /api/v1/policies/effective` and cache the response locally.
+3. Evaluate runtime actions locally using cached policy and the bundled local engine.
+4. Write local audit JSONL before any Cloud sync.
+5. Upload redacted audit events to `POST /api/v1/events/ingest`.
+6. For `require_approval`, create `POST /api/v1/approvals` and block the action until reviewed.
+7. Use `GET /api/v1/sessions/:sessionId/timeline` for review/debug UI.
+
+If Cloud is unavailable, continue local enforcement using cached policy, then bundled default policy.
+
+## Decision values
+
+Cloud returns:
+
+```text
+allow | warn | require_approval | block
+```
+
+Native UI may present `require_approval` as `confirm`, but API payloads should keep the Cloud value.
+
+## Shared types
+
+### Agent hosts
+
+```text
+claude-code | codex | openclaw | cursor | gemini | copilot | other
+```
+
+### Action types
+
+```text
+shell | file_read | file_write | network | mcp_tool | browser | skill_install | deploy | other
+```
+
+### Risk levels
+
+```text
+safe | low | medium | high | critical
+```
+
+### Policy reason
+
+```json
+{
+  "code": "SECRET_ACCESS",
+  "severity": "high",
+  "title": "Protected path access",
+  "description": "The agent attempted to access a path protected by runtime policy.",
+  "evidence": "~/.ssh/id_rsa",
+  "remediation": "Require approval before this access."
+}
+```
+
+## API surface
+
+### Commercial install script
+
+```http
+GET /install.sh?agent=claude-code
+```
+
+Allowed `agent` values:
+
+```text
+auto | claude-code | openclaw | codex
+```
+
+The script installs `@goplus/agentguard`, writes a safe fallback local config, then calls:
+
+```bash
+agentguard init --agent "$AGENTGUARD_AGENT" --cloud "$AGENTGUARD_CLOUD_URL"
+agentguard connect --cloud "$AGENTGUARD_CLOUD_URL" --api-key "$AGENTGUARD_API_KEY"
+```
+
+Native CLI implementations should support `--cloud` as an alias for the Cloud URL and `--api-key` as an alias for the API key.
+
+### Health check
+
+```http
+GET /api/v1/status
+```
+
+Auth is not required.
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "status": "healthy",
+    "version": "1.0.0",
+    "timestamp": "2026-05-11T00:00:00.000Z"
+  }
+}
+```
+
+Native usage: `doctor` command and diagnostics.
+
+### Fetch effective policy
+
+```http
+GET /api/v1/policies/effective
+X-API-Key: ag_live_xxxxx
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "policyVersion": "runtime-v0.1",
+    "mode": "balanced",
+    "decisions": {
+      "destructiveCommand": "block",
+      "remoteCodeExecution": "block",
+      "dataExfiltration": "block",
+      "secretAccess": "require_approval",
+      "deployAction": "require_approval"
+    },
+    "protectedPaths": ["~/.ssh/**", "~/.aws/**", "**/.env*"],
+    "blockedCommandPatterns": ["rm -rf /", "curl ... | bash"],
+    "allowedCommandPatterns": [],
+    "approvalActionTypes": ["file_read", "file_write", "deploy"],
+    "network": {
+      "defaultOutbound": "warn",
+      "blockedDomains": ["discord.com/api/webhooks"],
+      "approvalDomains": []
+    },
+    "updatedAt": "2026-05-11T00:00:00.000Z"
+  }
+}
+```
+
+Native requirements:
+
+- Fetch during `connect`.
+- Refresh opportunistically before runtime evaluation.
+- Cache the last valid response.
+- Never disable local enforcement if this endpoint fails.
+
+### Cloud action evaluation
+
+```http
+POST /api/v1/actions/evaluate
+Content-Type: application/json
+X-API-Key: ag_live_xxxxx
+```
+
+Request:
+
+```json
+{
+  "sessionId": "sess_local_123",
+  "agentHost": "claude-code",
+  "actionType": "shell",
+  "toolName": "Bash",
+  "input": "curl https://example.com/install.sh | bash",
+  "cwd": "/workspace/app",
+  "sourceSkill": "optional-skill-id",
+  "metadata": {
+    "evaluation": "cloud"
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "actionId": "act_abc123",
+    "decision": "block",
+    "riskScore": 95,
+    "riskLevel": "critical",
+    "reasons": [],
+    "policyVersion": "runtime-v0.1"
+  }
+}
+```
+
+Native usage:
+
+- Optional. The preferred default is local-first evaluation.
+- Use when the native client intentionally wants Cloud-authoritative decisions.
+- Enforce the returned decision locally.
+
+### Ingest redacted audit events
+
+```http
+POST /api/v1/events/ingest
+Content-Type: application/json
+X-API-Key: ag_live_xxxxx
+```
+
+Request:
+
+```json
+{
+  "events": [
+    {
+      "actionId": "act_local_123",
+      "sessionId": "sess_local_123",
+      "agentHost": "codex",
+      "actionType": "shell",
+      "toolName": "Bash",
+      "input": "echo safe --api_key=[REDACTED]",
+      "decision": "warn",
+      "riskScore": 20,
+      "riskLevel": "medium",
+      "reasons": [],
+      "policyVersion": "runtime-v0.1",
+      "cwd": "/workspace/app",
+      "sourceSkill": "optional-skill-id",
+      "metadata": {
+        "evaluation": "local-oss"
+      }
+    }
+  ]
+}
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "accepted": 1,
+    "rejected": 0
+  }
+}
+```
+
+Limits and behavior:
+
+- Maximum `100` events per batch.
+- `input` should be a redacted preview, not full file content or full prompt content.
+- If upload fails, spool locally and retry later.
+
+### Create approval
+
+```http
+POST /api/v1/approvals
+Content-Type: application/json
+X-API-Key: ag_live_xxxxx
+```
+
+Request:
+
+```json
+{
+  "actionId": "act_local_123",
+  "sessionId": "sess_local_123",
+  "agentHost": "claude-code",
+  "actionType": "file_read",
+  "toolName": "Read",
+  "input": "~/.ssh/id_rsa",
+  "riskScore": 55,
+  "riskLevel": "high",
+  "reasons": [],
+  "policyVersion": "runtime-v0.1",
+  "cwd": "/workspace/app",
+  "sourceSkill": "optional-skill-id",
+  "metadata": {
+    "evaluation": "local-oss"
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "approvalId": "apr_abc123",
+    "actionId": "act_local_123",
+    "sessionId": "sess_local_123",
+    "status": "pending"
+  }
+}
+```
+
+Native behavior:
+
+- Create this only after local or Cloud decision returns `require_approval`.
+- Block the action while approval is pending.
+- Show the approval id to the user when available.
+
+### List approvals
+
+```http
+GET /api/v1/approvals?status=pending
+X-API-Key: ag_live_xxxxx
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "approvals": [
+      {
+        "approvalId": "apr_abc123",
+        "actionId": "act_local_123",
+        "sessionId": "sess_local_123",
+        "agentHost": "claude-code",
+        "actionType": "file_read",
+        "toolName": "Read",
+        "inputPreview": "~/.ssh/id_rsa",
+        "status": "pending",
+        "riskScore": 55,
+        "riskLevel": "high",
+        "reasons": [],
+        "policyVersion": "runtime-v0.1",
+        "createdAt": "2026-05-11T00:00:00.000Z"
+      }
+    ]
+  }
+}
+```
+
+Native usage: optional inbox UI or debugging command.
+
+### Review approval
+
+```http
+PATCH /api/v1/approvals/:approvalId
+Content-Type: application/json
+X-API-Key: ag_live_xxxxx
+```
+
+Request:
+
+```json
+{
+  "status": "approved",
+  "note": "Expected deploy"
+}
+```
+
+`status` must be either `approved` or `denied`.
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "approvalId": "apr_abc123",
+    "actionId": "act_local_123",
+    "sessionId": "sess_local_123",
+    "status": "approved"
+  }
+}
+```
+
+Native usage: optional reviewer UX. Most local hooks should simply block and ask the user to review in Cloud.
+
+### Session timeline
+
+```http
+GET /api/v1/sessions/:sessionId/timeline
+X-API-Key: ag_live_xxxxx
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "sessionId": "sess_local_123",
+    "events": [
+      {
+        "actionId": "act_local_123",
+        "sessionId": "sess_local_123",
+        "agentHost": "codex",
+        "actionType": "shell",
+        "toolName": "Bash",
+        "inputPreview": "echo safe",
+        "decision": "allow",
+        "riskScore": 0,
+        "riskLevel": "safe",
+        "reasons": [],
+        "policyVersion": "runtime-v0.1",
+        "approvalStatus": null,
+        "createdAt": "2026-05-11T00:00:00.000Z"
+      }
+    ]
+  }
+}
+```
+
+Native usage: optional status/debug command and incident review.
+
+## Supply-chain scan APIs
+
+These are Cloud scan APIs rather than runtime control-plane APIs. Native clients may use them for paid/deep scans, but local scan should still work without Cloud.
+
+### Scan content
+
+```http
+POST /api/v1/scan
+Content-Type: application/json
+X-API-Key: ag_live_xxxxx
+```
+
+Request:
+
+```json
+{
+  "content": "# SKILL.md content",
+  "context": {
+    "registry": "github.com/org/repo",
+    "author": "org",
+    "version": "v1.0.0"
+  },
+  "ai": false
+}
+```
+
+### Scan URL
+
+```http
+POST /api/v1/scan-url
+Content-Type: application/json
+X-API-Key: ag_live_xxxxx
+```
+
+Request:
+
+```json
+{
+  "url": "https://github.com/org/repo/blob/main/SKILL.md",
+  "type": "github",
+  "ai": false
+}
+```
+
+### Scan registry
+
+```http
+POST /api/v1/scan-registry
+Content-Type: application/json
+X-API-Key: ag_live_xxxxx
+```
+
+Request:
+
+```json
+{
+  "registry": "https://example-registry.invalid",
+  "limit": 50,
+  "offset": 0,
+  "filter": "latest"
+}
+```
+
+Valid `filter` values:
+
+```text
+latest | popular | all
+```
+
+## Privacy rules for native clients
+
+Native clients must redact before upload:
+
+- API keys
+- Bearer tokens
+- private key PEM blocks
+- URL query secrets
+- env-style secrets such as `api_key=...`, `token=...`, `password=...`
+
+Native clients should upload only:
+
+- action metadata
+- redacted input preview
+- decision/risk/reasons
+- policy version
+- optional source skill and cwd
+
+Native clients should not upload by default:
+
+- full file contents
+- full prompts
+- full command output
+- full secrets
+
+## Error handling
+
+Expected native behavior:
+
+- `401`: API key missing/invalid. Continue local-only mode and ask user to reconnect.
+- `403`: plan/tier does not allow the endpoint. Continue local protection.
+- `429`: rate limited. Queue audit events and retry later.
+- `5xx`: Cloud unavailable or server write failed. Continue local enforcement and spool events.
+
+Never fail open for a local `block` decision.

package/docs/codex.md

@@ -0,0 +1,38 @@
+# Codex
+
+Codex can use AgentGuard as a local skill/runtime template for command, file, and network review.
+
+## Local commands
+
+```bash
+npm install -g @goplus/agentguard
+agentguard init
+agentguard scan ./skills/example
+```
+
+## Runtime template
+
+To write Codex templates in the current project:
+
+```bash
+agentguard init --agent codex
+```
+
+This creates `.codex/skills/agentguard/SKILL.md` and `.codex/agentguard-hook.example.json`.
+
+Pipe a tool event to `agentguard protect`:
+
+```bash
+printf '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' \
+  | AGENTGUARD_AGENT_HOST=codex agentguard protect --json
+```
+
+Use these mappings for Codex-style hooks or skills:
+
+- shell commands → `shell`
+- file reads → `file_read`
+- file writes/patches → `file_write`
+- browser/network fetches → `network`
+- MCP tool calls → `mcp_tool`
+
+When Cloud is connected, Codex events are synced as redacted previews and can participate in Cloud approvals.

package/docs/goplus-api.md

@@ -0,0 +1,38 @@
+# GoPlus API Integration
+
+GoPlus AgentGuard optionally integrates with the [GoPlus Security API](https://gopluslabs.io/security-api) for enhanced Web3 security.
+
+## Setup
+
+```bash
+export GOPLUS_API_KEY=your_key
+export GOPLUS_API_SECRET=your_secret
+```
+
+Get keys at: https://gopluslabs.io/security-api
+
+## What It Adds
+
+Without GoPlus API, AgentGuard uses local pattern matching for Web3 security (unlimited approvals, reentrancy, selfdestruct, etc.).
+
+With GoPlus API, you get additional capabilities:
+
+- **Token Security**: Check if a token is a honeypot, has a tax, or has other risks
+- **Address Security**: Check if an address is associated with phishing, scams, or malicious activity
+- **Transaction Simulation**: Simulate a transaction to see its effects before execution
+- **Approval Security**: Check for risky token approvals
+- **dApp Security**: Verify the safety of decentralized applications
+
+## Graceful Degradation
+
+If the GoPlus API is unavailable or keys are not configured, AgentGuard falls back to local-only analysis. No functionality is lost — you just get fewer Web3-specific insights.
+
+## External Scanner
+
+GoPlus AgentGuard also integrates with [cisco-ai-defense/skill-scanner](https://github.com/cisco-ai-defense/skill-scanner) for additional scanning capabilities:
+
+```bash
+pip install cisco-ai-skill-scanner
+```
+
+This adds YAML/YARA pattern scanning, Python AST analysis, and VirusTotal integration.

package/docs/mcp-server.md

@@ -0,0 +1,39 @@
+# MCP Server
+
+AgentGuard still ships an MCP server for hosts that prefer MCP tools over hooks.
+
+## Run
+
+```bash
+npx -y --package @goplus/agentguard agentguard-mcp
+```
+
+If installed globally:
+
+```bash
+agentguard-mcp
+```
+
+## Configure
+
+```json
+{
+  "mcpServers": {
+    "agentguard": {
+      "command": "agentguard-mcp"
+    }
+  }
+}
+```
+
+## Tools
+
+- `skill_scanner_scan`
+- `registry_lookup`
+- `registry_attest`
+- `registry_revoke`
+- `registry_list`
+- `action_scanner_decide`
+- `action_scanner_simulate_web3`
+
+For live action blocking, prefer `agentguard protect` hooks. MCP is best for agent-invoked scans, trust registry operations, and Web3 simulation.