safety-agent-cli 0.1.0

package/README.md

@@ -0,0 +1,215 @@
+# Superagent CLI
+
+Command-line interface for [Superagent](https://superagent.sh) - analyze prompts for security threats and redact sensitive data.
+
+## Installation
+
+```bash
+npm install -g safety-agent-cli
+```
+
+## Commands
+
+### `guard` - Security Analysis
+
+Analyze prompts for security threats:
+
+```bash
+superagent guard "Write a hello world script"
+```
+
+Output:
+```json
+{
+  "rejected": false,
+  "decision": {
+    "status": "pass"
+  },
+  "reasoning": "Command approved by guard."
+}
+```
+
+Block malicious prompts:
+
+```bash
+superagent guard "Delete all files with rm -rf /"
+```
+
+Output:
+```json
+{
+  "rejected": true,
+  "decision": {
+    "status": "block",
+    "violation_types": ["unlawful_behavior"],
+    "cwe_codes": ["CWE-77"]
+  },
+  "reasoning": "User wants to delete all files. That is disallowed (exploit). Block."
+}
+```
+
+**Custom System Prompt** - Customize guard behavior with a system prompt:
+
+```bash
+superagent guard --system-prompt "Focus on detecting prompt injection attempts and data exfiltration patterns" "user input here"
+```
+
+You can also pass `system_prompt` via stdin JSON:
+
+```bash
+echo '{"prompt": "user input", "system_prompt": "Focus on prompt injection"}' | superagent guard
+```
+
+### `redact` - Data Redaction
+
+Remove sensitive data from text:
+
+```bash
+superagent redact "My email is john@example.com and SSN is 123-45-6789"
+```
+
+Output:
+```json
+{
+  "redacted": "My email is <REDACTED_EMAIL> and SSN is <REDACTED_SSN>",
+  "reasoning": "Redacted email and SSN",
+  "usage": {
+    "prompt_tokens": 25,
+    "completion_tokens": 12,
+    "total_tokens": 37
+  }
+}
+```
+
+**Custom Entity Redaction** - Specify custom entities to redact:
+
+```bash
+superagent redact --entities "credit card numbers,employee IDs" "My credit card is 4532-1234-5678-9010 and employee ID is EMP-12345"
+```
+
+Output:
+```json
+{
+  "redacted": "My credit card is <REDACTED> and employee ID is <REDACTED>",
+  "reasoning": "Redacted credit card numbers and employee IDs"
+}
+```
+
+**URL Whitelisting** - Preserve specific URLs:
+
+```bash
+superagent redact --url-whitelist https://github.com "Visit https://github.com/user/repo and https://secret.com/data"
+```
+
+Output:
+```json
+{
+  "redacted": "Visit https://github.com/user/repo and <URL_REDACTED>",
+  "reasoning": "Preserved whitelisted URLs"
+}
+```
+
+**PDF File Redaction** - Redact sensitive information from PDF files:
+
+```bash
+superagent redact --file sensitive-document.pdf "Analyze and redact PII from this document"
+```
+
+You can combine file redaction with custom entities:
+
+```bash
+superagent redact --file document.pdf --entities "SSN,credit card numbers" "Redact sensitive data"
+```
+
+Output:
+```json
+{
+  "redacted": "Redacted text content from the PDF with sensitive data removed",
+  "reasoning": "Redacted SSN and credit card numbers from PDF document",
+  "usage": {
+    "prompt_tokens": 150,
+    "completion_tokens": 45,
+    "total_tokens": 195
+  }
+}
+```
+
+**Note:** File redaction currently supports PDF format only.
+
+## Help
+
+Get help for any command:
+
+```bash
+superagent --help
+superagent guard --help
+superagent redact --help
+```
+
+### Claude Code Hook
+
+Validate all prompts before Claude processes them by adding a hook to your `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "SUPERAGENT_API_KEY": "your_api_key_here"
+  },
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "superagent guard"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The CLI will:
+- ✅ Allow safe prompts to proceed
+- 🛡️ Block malicious prompts with detailed reasoning
+- 🔍 Show violation types and CWE codes for blocked prompts
+
+### Environment Variables
+
+- `SUPERAGENT_API_KEY` - Your Superagent API key (required)
+
+Get your API key at [app.superagent.sh](https://app.superagent.sh)
+
+## How It Works
+
+The CLI uses [Superagent](https://superagent.sh) to analyze prompts for:
+
+- **Security vulnerabilities** (SQL injection, command injection, etc.)
+- **Malicious intent** (data destruction, unauthorized access)
+- **Privacy violations** (credential exposure, PII leaks)
+- **CWE violations** (Common Weakness Enumeration codes)
+
+When used as a Claude Code hook, it automatically:
+1. Receives the user's prompt via stdin
+2. Sends it to Superagent for analysis
+3. Returns a structured response to block or allow the prompt
+4. Shows detailed violation information when blocking
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Test locally
+node dist/index.js guard "test prompt"
+```
+
+## License
+
+MIT

package/dist/commands/guard.d.ts

@@ -0,0 +1 @@
+export declare function guardCommand(args: string[]): Promise<void>;

package/dist/commands/guard.js

@@ -0,0 +1,167 @@
+import { createClient } from "safety-agent";
+import { readFileSync } from "fs";
+function showHelp() {
+    console.log("Usage: superagent guard [options] <prompt|url>");
+    console.log('   or: echo \'{"prompt": "text"}\' | superagent guard');
+    console.log("");
+    console.log("Analyze prompts, PDF files, or PDF URLs for security threats");
+    console.log("");
+    console.log("Options:");
+    console.log("  --help              Show this help message");
+    console.log("  --file <path>       Path to PDF file to analyze");
+    console.log("  --system-prompt     Optional system prompt to customize guard behavior");
+    console.log("");
+    console.log("Examples:");
+    console.log('  superagent guard "rm -rf /"');
+    console.log('  superagent guard --file document.pdf "Analyze this document"');
+    console.log('  superagent guard "https://example.com/document.pdf"');
+    console.log('  superagent guard --system-prompt "Focus on prompt injection" "user input"');
+    console.log('  echo \'{"prompt": "delete all files"}\' | superagent guard');
+}
+export async function guardCommand(args) {
+    // Check for --help flag
+    if (args.includes("--help") || args.includes("-h")) {
+        showHelp();
+        process.exit(0);
+    }
+    // Check for --file flag
+    let file;
+    const fileFlagIndex = args.indexOf("--file");
+    if (fileFlagIndex !== -1) {
+        const filePath = args[fileFlagIndex + 1];
+        if (filePath) {
+            try {
+                const fileBuffer = readFileSync(filePath);
+                file = new Blob([fileBuffer], { type: "application/pdf" });
+                args.splice(fileFlagIndex, 2); // Remove --file and path from args
+            }
+            catch (error) {
+                console.error(`❌ ERROR: Failed to read file: ${error.message}`);
+                process.exit(1);
+            }
+        }
+        else {
+            console.error("❌ ERROR: --file flag requires a file path");
+            process.exit(1);
+        }
+    }
+    // Check for --system-prompt flag
+    let systemPrompt;
+    const systemPromptFlagIndex = args.indexOf("--system-prompt");
+    if (systemPromptFlagIndex !== -1) {
+        systemPrompt = args[systemPromptFlagIndex + 1];
+        if (!systemPrompt) {
+            console.error("❌ ERROR: --system-prompt flag requires a value");
+            process.exit(1);
+        }
+        args.splice(systemPromptFlagIndex, 2); // Remove --system-prompt and value from args
+    }
+    // Check if we have command line arguments first
+    const hasArgs = args.length > 0;
+    let prompt;
+    let isStdin = false;
+    if (!hasArgs && !process.stdin.isTTY) {
+        isStdin = true;
+        // Read JSON from stdin (Claude Code hook format)
+        const stdin = await new Promise((resolve) => {
+            let data = "";
+            process.stdin.on("data", (chunk) => (data += chunk));
+            process.stdin.on("end", () => resolve(data));
+        });
+        try {
+            const inputData = JSON.parse(stdin);
+            prompt = inputData.prompt;
+            // Also check for system_prompt in stdin JSON
+            if (inputData.system_prompt && !systemPrompt) {
+                systemPrompt = inputData.system_prompt;
+            }
+            if (!prompt) {
+                console.error("❌ ERROR: No prompt provided in stdin JSON");
+                process.exit(2);
+            }
+        }
+        catch (error) {
+            console.error("❌ ERROR: Failed to parse JSON from stdin");
+            process.exit(2);
+        }
+    }
+    else {
+        // Command line argument
+        prompt = args.join(" ");
+        if (!prompt) {
+            console.error("Usage: superagent guard <prompt>");
+            console.error('   or: echo \'{"prompt": "text"}\' | superagent guard');
+            process.exit(1);
+        }
+    }
+    // Ensure API key is available
+    if (!process.env.SUPERAGENT_API_KEY) {
+        console.error("❌ ERROR: SUPERAGENT_API_KEY environment variable not set");
+        process.exit(2);
+    }
+    // Create client instance
+    const client = createClient({
+        apiKey: process.env.SUPERAGENT_API_KEY,
+    });
+    try {
+        // Pass file as first parameter if provided, otherwise pass prompt
+        const input = file || prompt;
+        const result = await client.guard({ input, systemPrompt });
+        const { classification, violation_types, cwe_codes, usage } = result;
+        const isBlocked = classification === "block";
+        if (isBlocked) {
+            if (isStdin) {
+                // Claude Code hook format
+                const violationInfo = violation_types?.length
+                    ? ` Violations: ${violation_types.join(", ")}.`
+                    : "";
+                const cweInfo = cwe_codes?.length
+                    ? ` CWE: ${cwe_codes.join(", ")}.`
+                    : "";
+                const response = {
+                    decision: "block",
+                    reason: `🛡️ Superagent Guard blocked this prompt.${violationInfo}${cweInfo}`,
+                    hookSpecificOutput: {
+                        hookEventName: "UserPromptSubmit",
+                        additionalContext: `Blocked by Superagent Guard`,
+                    },
+                };
+                console.log(JSON.stringify(response));
+            }
+            else {
+                // CLI output - JSON format matching SDK
+                const output = {
+                    classification,
+                    violation_types,
+                    cwe_codes,
+                    usage,
+                };
+                console.log(JSON.stringify(output, null, 2));
+                process.exit(1);
+            }
+        }
+        else {
+            if (!isStdin) {
+                // CLI output - JSON format matching SDK
+                const output = {
+                    classification,
+                    violation_types,
+                    cwe_codes,
+                    usage,
+                };
+                console.log(JSON.stringify(output, null, 2));
+            }
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`⚠️ Guard check failed: ${error.message}`);
+        if (isStdin) {
+            console.error("Allowing prompt to proceed...");
+            process.exit(0);
+        }
+        else {
+            process.exit(2);
+        }
+    }
+}

package/dist/commands/redact.d.ts

@@ -0,0 +1 @@
+export declare function redactCommand(args: string[]): Promise<void>;

package/dist/commands/redact.js

@@ -0,0 +1,103 @@
+import { createClient } from "safety-agent";
+export async function redactCommand(args) {
+    // Check for --entities flag
+    const entitiesFlagIndex = args.indexOf("--entities");
+    let entities;
+    if (entitiesFlagIndex !== -1) {
+        // Get the value after --entities (comma-separated entities)
+        const entitiesValue = args[entitiesFlagIndex + 1];
+        if (entitiesValue) {
+            entities = entitiesValue.split(",").map((entity) => entity.trim());
+            // Remove --entities and its value from args
+            args.splice(entitiesFlagIndex, 2);
+        }
+        else {
+            console.error("❌ ERROR: --entities requires a comma-separated list of entity types");
+            process.exit(1);
+        }
+    }
+    // Check for --rewrite flag
+    const rewriteFlagIndex = args.indexOf("--rewrite");
+    let rewrite;
+    if (rewriteFlagIndex !== -1) {
+        rewrite = true;
+        // Remove --rewrite from args
+        args.splice(rewriteFlagIndex, 1);
+    }
+    // Check if we have command line arguments first
+    const hasArgs = args.length > 0;
+    let text;
+    let isStdin = false;
+    if (!hasArgs && !process.stdin.isTTY) {
+        isStdin = true;
+        // Read JSON from stdin
+        const stdin = await new Promise((resolve) => {
+            let data = "";
+            process.stdin.on("data", (chunk) => (data += chunk));
+            process.stdin.on("end", () => resolve(data));
+        });
+        try {
+            const inputData = JSON.parse(stdin);
+            text = inputData.text || inputData.prompt;
+            // Check for rewrite in stdin JSON
+            if (inputData.rewrite !== undefined) {
+                rewrite = Boolean(inputData.rewrite);
+            }
+            if (!text) {
+                console.error("❌ ERROR: No text provided in stdin JSON");
+                process.exit(2);
+            }
+        }
+        catch (error) {
+            console.error("❌ ERROR: Failed to parse JSON from stdin");
+            process.exit(2);
+        }
+    }
+    else {
+        // Command line argument
+        text = args.join(" ");
+        if (!text) {
+            console.error("Usage: superagent redact [--entities <entity1,entity2>] [--rewrite] <text>");
+            console.error('   or: echo \'{"text": "..."}\' | superagent redact [--entities <entity1,entity2>] [--rewrite]');
+            console.error("");
+            console.error("Options:");
+            console.error("  --entities <entities>     Comma-separated list of entity types to redact");
+            console.error("  --rewrite                 Naturally rewrite content instead of using placeholders");
+            console.error("");
+            console.error("Examples:");
+            console.error('  superagent redact "My email is john@example.com"');
+            console.error('  superagent redact --entities "emails,phones" "Contact: john@example.com, 555-1234"');
+            console.error('  superagent redact --rewrite "Contact me at john@example.com"');
+            process.exit(1);
+        }
+    }
+    // Ensure API key is available
+    if (!process.env.SUPERAGENT_API_KEY) {
+        console.error("❌ ERROR: SUPERAGENT_API_KEY environment variable not set");
+        process.exit(2);
+    }
+    // Create client instance
+    const client = createClient({
+        apiKey: process.env.SUPERAGENT_API_KEY,
+    });
+    try {
+        const result = await client.redact({
+            input: text,
+            model: "openai/gpt-4o-mini",
+            entities,
+            rewrite,
+        });
+        // JSON output
+        const output = {
+            redacted: result.redacted,
+            findings: result.findings,
+            usage: result.usage,
+        };
+        console.log(JSON.stringify(output, null, 2));
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`⚠️ Redact failed: ${error.message}`);
+        process.exit(2);
+    }
+}

package/dist/commands/verify.d.ts

@@ -0,0 +1 @@
+export declare function verifyCommand(args: string[]): Promise<void>;

package/dist/commands/verify.js

@@ -0,0 +1,137 @@
+import { createClient } from 'superagent-ai';
+function showHelp() {
+    console.log('Usage: superagent verify [options] <text>');
+    console.log('   or: echo \'{"text": "...", "sources": [...]}\' | superagent verify');
+    console.log('');
+    console.log('Verify claims in text against source materials');
+    console.log('');
+    console.log('Options:');
+    console.log('  --help            Show this help message');
+    console.log('  --sources <json>  JSON string containing array of sources');
+    console.log('');
+    console.log('Source format:');
+    console.log('  [{"name": "Source Name", "content": "...", "url": "https://..."}]');
+    console.log('');
+    console.log('Examples:');
+    console.log('  superagent verify --sources \'[{"name":"About","content":"Founded in 2020"}]\' "The company was founded in 2020"');
+    console.log('  echo \'{"text": "...", "sources": [...]}\' | superagent verify');
+}
+export async function verifyCommand(args) {
+    // Check for --help flag
+    if (args.includes('--help') || args.includes('-h')) {
+        showHelp();
+        process.exit(0);
+    }
+    // Check for --sources flag
+    let sources;
+    const sourcesFlagIndex = args.indexOf('--sources');
+    if (sourcesFlagIndex !== -1) {
+        const sourcesJson = args[sourcesFlagIndex + 1];
+        if (sourcesJson) {
+            try {
+                sources = JSON.parse(sourcesJson);
+                if (!Array.isArray(sources)) {
+                    console.error('❌ ERROR: --sources must be a JSON array');
+                    process.exit(1);
+                }
+                // Remove --sources and its value from args
+                args.splice(sourcesFlagIndex, 2);
+            }
+            catch (error) {
+                console.error(`❌ ERROR: Failed to parse sources JSON: ${error.message}`);
+                process.exit(1);
+            }
+        }
+        else {
+            console.error('❌ ERROR: --sources flag requires a JSON string');
+            process.exit(1);
+        }
+    }
+    // Check if we have command line arguments first
+    const hasArgs = args.length > 0;
+    let text;
+    let isStdin = false;
+    if (!hasArgs && !process.stdin.isTTY) {
+        isStdin = true;
+        // Read JSON from stdin
+        const stdin = await new Promise((resolve) => {
+            let data = '';
+            process.stdin.on('data', chunk => data += chunk);
+            process.stdin.on('end', () => resolve(data));
+        });
+        try {
+            const inputData = JSON.parse(stdin);
+            text = inputData.text;
+            // Get sources from stdin if not provided via command line
+            if (!sources && inputData.sources) {
+                sources = inputData.sources;
+            }
+            if (!text) {
+                console.error('❌ ERROR: No text provided in stdin JSON');
+                process.exit(2);
+            }
+        }
+        catch (error) {
+            console.error('❌ ERROR: Failed to parse JSON from stdin');
+            process.exit(2);
+        }
+    }
+    else {
+        // Command line argument
+        text = args.join(' ');
+        if (!text) {
+            showHelp();
+            process.exit(1);
+        }
+    }
+    // Validate sources
+    if (!sources || !Array.isArray(sources) || sources.length === 0) {
+        console.error('❌ ERROR: sources are required. Use --sources flag or provide via stdin');
+        console.error('');
+        showHelp();
+        process.exit(1);
+    }
+    // Validate each source
+    for (const source of sources) {
+        if (!source.content || typeof source.content !== 'string') {
+            console.error('❌ ERROR: Each source must have a "content" field (string)');
+            process.exit(1);
+        }
+        if (!source.name || typeof source.name !== 'string') {
+            console.error('❌ ERROR: Each source must have a "name" field (string)');
+            process.exit(1);
+        }
+        if (source.url !== undefined && typeof source.url !== 'string') {
+            console.error('❌ ERROR: If provided, "url" must be a string');
+            process.exit(1);
+        }
+    }
+    // Ensure API key is available
+    if (!process.env.SUPERAGENT_API_KEY) {
+        console.error('❌ ERROR: SUPERAGENT_API_KEY environment variable not set');
+        process.exit(2);
+    }
+    // Create client instance
+    const client = createClient({
+        apiKey: process.env.SUPERAGENT_API_KEY,
+    });
+    try {
+        const result = await client.verify(text, sources);
+        const output = {
+            claims: result.claims,
+            usage: result.usage,
+        };
+        console.log(JSON.stringify(output, null, 2));
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`⚠️ Verify failed: ${error.message}`);
+        if (isStdin) {
+            console.error('Allowing to proceed...');
+            process.exit(0);
+        }
+        else {
+            process.exit(2);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { guardCommand } from './commands/guard.js';
+import { redactCommand } from './commands/redact.js';
+function showHelp() {
+    console.log('Usage: superagent <command> [options]');
+    console.log('');
+    console.log('AI security and privacy toolkit');
+    console.log('');
+    console.log('Commands:');
+    console.log('  guard   Analyze prompts for security threats');
+    console.log('  redact  Remove sensitive data from text');
+    console.log('');
+    console.log('Options:');
+    console.log('  --help  Show help for a command');
+    console.log('');
+    console.log('Examples:');
+    console.log('  superagent guard --help');
+    console.log('  superagent redact --help');
+    console.log('  superagent guard "rm -rf /"');
+    console.log('  superagent redact "My email is john@example.com"');
+}
+const args = process.argv.slice(2);
+const command = args[0];
+if (!command || command === '--help' || command === '-h') {
+    showHelp();
+    process.exit(0);
+}
+switch (command) {
+    case 'guard':
+        await guardCommand(args.slice(1));
+        break;
+    case 'redact':
+        await redactCommand(args.slice(1));
+        break;
+    default:
+        console.error(`Unknown command: ${command}`);
+        console.error('');
+        showHelp();
+        process.exit(1);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "safety-agent-cli",
+  "version": "0.1.0",
+  "description": "CLI for Superagent - validate prompts and tool calls for security",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "superagent": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "superagent",
+    "guard",
+    "cli",
+    "security",
+    "claude-code",
+    "hooks",
+    "ai-safety"
+  ],
+  "author": "Superagent",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/superagent-ai/superagent"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "dotenv": "^16.3.1",
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "safety-agent": "^0.1.0"
+  }
+}