@aivorynet/guard/README.md

AIVory Guard - MCP server for AI-powered compliance scanning. Integrates with Claude Code, Cursor, and other AI coding assistants.

# AIVory Guard

**AI-Powered Compliance Scanning for Your Coding Assistant**

AIVory Guard is an MCP (Model Context Protocol) server that enables AI coding assistants like Claude Code, Cursor, and Windsurf to perform real-time compliance and security scanning during code generation.

## Features

- **Real-time Security Scanning** - Catch vulnerabilities as code is generated
- **15+ Compliance Standards** - OWASP, GDPR, HIPAA, PCI-DSS, SOC2, ISO27001, and more
- **AI Code Detection** - Identify AI-generated code patterns (Copilot, Claude, ChatGPT, Cursor)
- **Git Integration** - Automatic branch/commit tracking for all batch scans
- **AI-Powered Analysis** - Deep learning models detect complex security issues
- **Fast Integration** - 5-minute setup with any MCP-compatible AI agent
- **Dashboard Analytics** - Track compliance trends and AI code usage over time
- **Zero False Positives** - AI analysis reduces noise vs. traditional static analysis

## Quick Start

### Prerequisites

- Node.js 18+ installed
- **Optional**: API token from AIVory for advanced compliance standards

**Note**: OWASP scans work without authentication. An API token is only required for GDPR, HIPAA, PCI-DSS, SOC2, ISO27001, and other advanced standards.

### Installation

```bash
# Install globally
npm install -g @aivorynet/guard

# Or use npx (no install needed)
npx @aivorynet/guard init
```

### Configuration

**For OWASP scans only** (no authentication required):
```bash
# Test without API key - OWASP scans only
npx @aivorynet/guard test
```

**For all compliance standards** (API key required):
```bash
# Run interactive setup wizard to configure API key
npx @aivorynet/guard init

# Test authenticated connection
npx @aivorynet/guard test
```

## Authentication

AIVory Guard supports **two usage modes**:

### 1. Unauthenticated Mode (OWASP Only - FREE)
No API key required. Provides OWASP Top 10 security scanning.

```bash
# Connect without API key - OWASP scans only
claude mcp add --transport stdio aivory -- npx -y @aivorynet/guard
```

### 2. Authenticated Mode (All Standards)
Requires API token. Unlocks **15+ compliance standards**: GDPR, HIPAA, PCI-DSS, SOC2, ISO27001, TISAX, DORA, NIS2, EU AI Act, and more.

**Get your API token** at: https://app.aivory.net/tokens

```bash
# Connect with API key - All compliance standards
claude mcp add --transport stdio aivory \
  --env AIVORY_API_KEY=your_api_key_here \
  -- npx -y @aivorynet/guard
```

### Connect to AI Agent

#### Claude Code (Recommended: CLI Method)

```bash
# Production - OWASP only (no API key)
claude mcp add --transport stdio aivory -- npx -y @aivorynet/guard

# Production - All standards (with API key)
claude mcp add --transport stdio aivory \
  --env AIVORY_API_KEY=your_api_key_here \
  -- npx -y @aivorynet/guard

# Local development (custom backend URL + API key)
claude mcp add --transport stdio aivory \
  --env AIVORY_API_KEY=your_api_key_here \
  --env AIVORY_SERVER_URL=http://localhost:8080 \
  -- npx -y @aivorynet/guard

# Verify installation
claude mcp list

# Test the connection
/mcp  # In Claude Code
```

**Windows Users:** The above commands work in PowerShell. For cmd.exe, use one line:
```cmd
claude mcp add --transport stdio aivory --env AIVORY_API_KEY=your_key --env AIVORY_SERVER_URL=http://localhost:8080 -- npx -y @aivorynet/guard
```

#### Claude Code (Alternative: Manual JSON Config)

Edit `~/.config/claude/mcp.json` (Linux/macOS) or `%USERPROFILE%\.claude\mcp.json` (Windows):

```json
{
  "mcpServers": {
    "aivory": {
      "command": "npx",
      "args": ["-y", "@aivorynet/guard"],
      "env": {
        "AIVORY_API_KEY": "your_api_key_here",
        "AIVORY_SERVER_URL": "https://app.aivory.net"
      }
    }
  }
}
```

#### Cursor

Create `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "aivory": {
      "command": "npx",
      "args": ["--yes", "@aivorynet/guard"],
      "env": {
        "AIVORY_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Usage

Once configured, your AI coding assistant will automatically scan code for compliance issues and detect AI-generated code:

### Compliance Scanning Example

```
You: "Write a user authentication function in Java"

AI: [Generates code and uses AIVory Guard to scan it]

AI: "I've created the authentication function with BCrypt password hashing
     and rate limiting. The compliance scan found 0 violations - the code
     meets OWASP and GDPR standards!"
```

### AI Detection Example

```
You: "Check if this code was AI-generated"

AI: [Uses scan_ai_detection tool]

AI: "The code shows patterns consistent with AI generation:
     - Confidence: 87.3%
     - Suspected Tool: GitHub Copilot
     - This code appears to be AI-generated based on comment patterns,
       variable naming conventions, and code structure."
```

### Batch Scanning with Git Tracking

Both compliance and AI detection batch scans automatically detect git information:

```
You: "Scan all my Python files for compliance issues"

AI: [Uses batch_scan tool which auto-detects git info]

AI: "Batch scan complete for project 'my-app':
     - Branch: feature-auth
     - Commit: abc1234
     - 15 files scanned
     - 3 violations found (2 medium, 1 low)

     Results saved to AIVory dashboard for tracking."
```

## Available Tools

AIVory Guard exposes 8 MCP tools to AI agents:

### Compliance Scanning
- **`scan_code`** - Scan a single file for compliance violations across 15+ standards
- **`batch_scan`** - Scan multiple files efficiently (auto-detects git info)
- **`dashboard`** - Get comprehensive compliance dashboard with trends and metrics

### AI Code Detection
- **`scan_ai_detection`** - Detect AI-generated code in a single file
- **`batch_scan_ai_detection`** - Detect AI-generated code across multiple files (saves to database with git tracking)

### Configuration & Utilities
- **`get_config`** - Get current compliance configuration
- **`get_rules`** - List available compliance rules
- **`health_check`** - Verify backend connectivity

**Note**: All batch scan tools now automatically detect and include git information (branch, commit hash, project name) for enhanced tracking and analytics.

## Get API Token (Optional)

**API tokens are optional** - OWASP scans work without authentication.

### When Do You Need an API Token?

**You DON'T need a token if:**
- You only want OWASP Top 10 security scanning
- You're evaluating AIVory Guard

**You NEED a token if:**
- You want GDPR, HIPAA, PCI-DSS, SOC2, or ISO27001 scans
- You need industry-specific compliance standards
- You want AI-powered security analysis

### How to Get Your Token

1. Visit https://app.aivory.net/tokens
2. Generate a new API token
3. Configure it:
   ```bash
   npx @aivorynet/guard init
   # Or add directly to MCP config with --env AIVORY_API_KEY=your_token
   ```

### Local Development (Optional)

For local backend development:

```bash
# Set environment variable to use local backend
export AIVORY_SERVER_URL=http://localhost:19999

# Or add to .env file
echo "AIVORY_SERVER_URL=http://localhost:19999" >> .env

# Then run init
npx @aivorynet/guard init
```

## Testing

Test your setup:

```bash
npx @aivorynet/guard test
```

Expected output:
```
Configuration loaded
Server: https://app.aivory.net
Backend is healthy
Compliance scan completed

All tests passed!
```

## Documentation

- [Developer Guide](https://docs.aivory.net/guard/developer-guide)
- [API Reference](https://docs.aivory.net/guard/api-reference)
- [Troubleshooting](https://docs.aivory.net/guard/troubleshooting)

## Support

- **Email**: support@aivory.net
- **Website**: https://aivory.net
- **Documentation**: https://docs.aivory.net

## Acknowledgments

Built with:
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io)
- [FastAPI](https://fastapi.tiangolo.com)
- [TypeScript](https://www.typescriptlang.org)

---

**Made by [AIVory](https://aivory.net)**