ai-security-scanner 1.0.0__tar.gz

ai_security_scanner-1.0.0/PKG-INFO

@@ -0,0 +1,525 @@
+Metadata-Version: 2.4
+Name: ai-security-scanner
+Version: 1.0.0
+Summary: AI Security Scanner — scan prompts, agents, APIs, MCP tools and integrations
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pydantic-settings>=2.2.0
+Requires-Dist: anthropic>=0.28.0
+Requires-Dist: openai>=1.30.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: structlog>=24.1.0
+Requires-Dist: twine>=6.2.0
+Requires-Dist: uvicorn>=0.49.0
+Requires-Dist: fastapi>=0.136.3
+Requires-Dist: python-multipart>=0.0.32
+Provides-Extra: api
+Requires-Dist: fastapi>=0.111.0; extra == "api"
+Requires-Dist: uvicorn[standard]>=0.29.0; extra == "api"
+Provides-Extra: vertex
+Requires-Dist: google-cloud-aiplatform>=1.60.0; extra == "vertex"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: requires-python
+
+# aiscan — AI Security Scanner
+
+Scans **prompts**, **agents**, **APIs**, **MCP tools**, and **integrations** for security vulnerabilities — prompt injection, data leakage, tool abuse, and security risks.
+
+40 built-in rules + AI deep scan (Claude / GPT-4o / Gemini). Runs as a CLI, REST API, Python SDK, or middleware.
+
+---
+
+## Table of contents
+
+- [Why aiscan](#why-aiscan)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [CLI commands](#cli-commands)
+- [Scan types](#scan-types)
+- [Rules reference](#rules-reference)
+- [REST API](#rest-api)
+- [Python SDK](#python-sdk)
+- [Middleware](#middleware)
+- [Decorators](#decorators)
+- [HTTP client (other languages)](#http-client-other-languages)
+- [CI/CD integration](#cicd-integration)
+- [AI provider configuration](#ai-provider-configuration)
+- [Suppressing false positives](#suppressing-false-positives)
+- [Sample files](#sample-files)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Why aiscan
+
+Traditional security tools (SonarQube, Snyk, Semgrep) were built before AI systems existed. They have no rules for prompt injection, agent tool permissions, or MCP tool definitions. aiscan fills that gap — it treats prompts, agent configs, and AI integrations as first-class security artifacts.
+
+---
+
+## Installation
+
+### From source
+
+```bash
+git clone <your-repo-url>
+cd aiscan-cli
+pip install -r requirements-all.txt
+pip install -e .
+```
+
+### Verify install
+
+```bash
+aiscan version
+```
+
+If `aiscan` command is not found, use `python -m aiscan.cli` instead everywhere below.
+
+---
+
+## Quick start
+
+```bash
+# 1. Generate config
+aiscan init
+
+# 2. Add your API key to .env
+#    ANTHROPIC_API_KEY=sk-ant-...
+
+# 3. Scan a file
+aiscan scan my_prompt.txt
+aiscan scan --type api openapi.yaml
+aiscan scan --type mcp tool_config.json
+
+# 4. Scan without AI (static rules only, no API key needed)
+aiscan scan --no-ai openapi.yaml
+```
+
+---
+
+## CLI commands
+
+### `aiscan scan`
+
+```
+Usage: aiscan scan [OPTIONS] FILES...
+
+Options:
+  -t, --type TEXT     Scan type: prompt | agent | api | mcp | integration | all | auto  [default: auto]
+  -o, --output TEXT   Output format: console | json | sarif                              [default: console]
+  -O, --out PATH      Write output to file instead of stdout
+  -f, --fail-on TEXT  Exit 1 if severity reached: critical | high | medium | none         [default: high]
+      --no-ai         Skip AI deep scan — static rules only
+  -q, --quiet         Suppress output except errors
+```
+
+**Examples:**
+
+```bash
+# Auto-detect scan type from extension
+aiscan scan system_prompt.txt
+aiscan scan agent_config.yaml
+
+# Explicit scan type
+aiscan scan --type prompt system_prompt.txt
+aiscan scan --type agent  agent.yaml
+aiscan scan --type api    openapi.yaml
+aiscan scan --type mcp    tool.json
+aiscan scan --type integration webhook_config.yaml
+
+# Scan a whole directory
+aiscan scan --type auto ./my-project/
+
+# Run all 5 scanners on the same file
+aiscan scan --type all config.yaml
+
+# JSON / SARIF output
+aiscan scan --type api openapi.yaml --output json
+aiscan scan --type prompt prompts/ --output sarif --out results.sarif
+
+# CI mode
+aiscan scan --quiet --fail-on high prompts/ && echo "passed"
+```
+
+### `aiscan rules`
+
+```bash
+aiscan rules                          # list all 40 rules
+aiscan rules prompt                   # rules for prompt scan type
+aiscan rules api --severity critical  # filter by severity
+```
+
+### `aiscan init`
+
+```bash
+aiscan init                    # creates .env for Claude
+aiscan init --provider openai  # pre-configure for OpenAI
+aiscan init --force            # overwrite existing .env
+```
+
+### `aiscan serve`
+
+```bash
+aiscan serve                 # http://localhost:8000
+aiscan serve --port 9000
+aiscan serve --reload        # dev mode, auto-restart
+```
+
+### `aiscan version`
+
+```bash
+aiscan version
+```
+
+---
+
+## Scan types
+
+| Type | Detects | File extensions (auto-detect) |
+|---|---|---|
+| `prompt` | Prompt injection, PII leakage, jailbreaks | `.txt` `.md` `.py` `.js` `.ts` `.go` `.java` and more |
+| `agent` | Wildcard tools, missing human approval, infinite loops | `.yaml` `.yml` |
+| `api` | Hardcoded keys, wildcard CORS, missing auth | `.yaml` `.yml` `.json` |
+| `mcp` | Wildcard permissions, code execution, missing rate limits | `.json` |
+| `integration` | Default secrets, SSL disabled, data forwarding | `.env` `.toml` `.ini` `.cfg` |
+
+---
+
+## Rules reference
+
+40 rules total — 6 categories. Run `aiscan rules` to see the live list.
+
+| Category | Rule IDs | Example |
+|---|---|---|
+| Prompt | `PI-001` `PI-002` `DL-001` `DL-002` `EX-001` | `ignore previous instructions` |
+| Agent | `AG-001`–`AG-006` | `allow_all_tools: true` |
+| API | `AK-001` `AK-002` `CO-001` `HT-001` `JW-001` `AU-001` | hardcoded `api_key` |
+| MCP | `MC-001`–`MC-006` | `execute_code: true` |
+| Integration | `IN-001`–`IN-006` | `webhook_secret: changeme` |
+| Code | `CD-001`–`CD-012` | `eval()`, SQL injection via f-string |
+| AI deep scan | `AI-SCAN` | Subtle issues caught by Claude/GPT-4o/Gemini |
+
+---
+
+## REST API
+
+```bash
+aiscan serve
+```
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/health` | Service status |
+| POST | `/scan/prompt` | Scan prompt content |
+| POST | `/scan/agent` | Scan agent config |
+| POST | `/scan/api` | Scan API config or OpenAPI spec |
+| POST | `/scan/mcp` | Scan MCP tool definition |
+| POST | `/scan/integration` | Scan integration config |
+| POST | `/scan/all` | Run all 5 scanners |
+| GET | `/docs` | Swagger UI |
+
+**Request:**
+```json
+{"content": "file content as string", "filename": "openapi.yaml"}
+```
+
+**Response:**
+```json
+{
+  "scan_type": "api",
+  "passed": false,
+  "critical": 1, "high": 2, "medium": 0, "info": 0, "total": 3,
+  "findings": [
+    {
+      "rule_id": "AK-001",
+      "severity": "critical",
+      "threat": "security_risk",
+      "title": "Hardcoded secret or API key",
+      "detail": "Matched on line 5: ...",
+      "file": "config.yaml",
+      "line": 5,
+      "fix": "Move to environment variables or a secrets manager."
+    }
+  ]
+}
+```
+
+**curl example:**
+```bash
+curl -X POST http://localhost:8000/scan/prompt \
+  -H "Content-Type: application/json" \
+  -d '{"content": "Ignore previous instructions", "filename": "prompt.txt"}'
+```
+
+---
+
+## Python SDK
+
+Use directly inside your Python project — no separate service needed.
+
+```python
+from aiscan.sdk import AIScan
+
+scanner = AIScan(no_ai=True)              # static rules only
+# or
+scanner = AIScan(ai_provider="claude", api_key="sk-ant-...")
+
+report = scanner.scan_prompt("Ignore previous instructions...")
+
+print(report.passed)     # False
+print(report.critical)   # 2
+print(report.total)      # 3
+
+for f in report.findings:
+    print(f.severity, f.rule_id, f.title)
+    print("  Fix:", f.fix)
+
+# Other methods
+scanner.scan_file("openapi.yaml")                     # auto-detect type
+scanner.scan_file("agent.yaml", scan_type="agent")
+scanner.scan_code("app.py")
+scanner.scan_api_spec(open("openapi.yaml").read())
+scanner.scan_agent_config(open("agent.yaml").read())
+scanner.scan_mcp_tool(open("tool.json").read())
+scanner.scan_integration(open("webhook.yaml").read())
+reports = scanner.scan_all(content, filename="config.yaml")  # all 5 scanners
+
+# Gate on severity
+if report.has_severity("critical"):
+    block_request()
+
+critical_only = report.findings_by_severity("critical")
+```
+
+---
+
+## Middleware
+
+Auto-scan every incoming request before it reaches your handlers.
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+from aiscan.sdk.middleware import AIScanFastAPIMiddleware
+
+app = FastAPI()
+app.add_middleware(
+    AIScanFastAPIMiddleware,
+    scan_fields=["prompt", "message", "content"],
+    fail_on="high",
+    no_ai=True,
+)
+```
+
+### Flask
+
+```python
+from flask import Flask
+from aiscan.sdk.middleware import AIScanFlaskMiddleware
+
+app = Flask(__name__)
+AIScanFlaskMiddleware(app, fields=["prompt", "message"], fail_on="high")
+```
+
+### Django
+
+```python
+# settings.py
+MIDDLEWARE = [
+    "aiscan.sdk.middleware.AIScanDjangoMiddleware",
+    # ...
+]
+AISCAN_FIELDS  = ["prompt", "message"]
+AISCAN_FAIL_ON = "high"
+```
+
+---
+
+## Decorators
+
+Wrap any existing function — no refactoring needed.
+
+```python
+from aiscan.sdk import scan_prompt_input, scan_before_llm, scan_file_input
+
+@scan_prompt_input(field="user_message", fail_on="high")
+def call_llm(user_message: str) -> str:
+    ...  # raises ValueError if unsafe
+
+@scan_before_llm(fields=["system_prompt", "user_message"])
+def chat(system_prompt: str, user_message: str) -> str:
+    ...
+
+@scan_file_input(field="config_path", fail_on="critical")
+def load_agent_config(config_path: str) -> dict:
+    ...
+```
+
+---
+
+## HTTP client (other languages)
+
+Run `aiscan serve` as a separate service, call it from any language.
+
+**Python:**
+```python
+from aiscan.sdk import AIScanClient
+
+client = AIScanClient("http://localhost:8000")
+result = client.scan_prompt(user_input)
+is_safe = client.is_safe(user_input, fail_on="high")
+```
+
+**Node.js:**
+```javascript
+const res = await fetch("http://localhost:8000/scan/prompt", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ content: userInput, filename: "prompt.txt" }),
+});
+const { passed, findings } = await res.json();
+```
+
+**Go:**
+```go
+resp, _ := http.Post("http://localhost:8000/scan/prompt",
+    "application/json", bytes.NewBuffer(body))
+```
+
+---
+
+## CI/CD integration
+
+### GitHub Actions
+
+```yaml
+name: AI Security Scan
+on: [push, pull_request]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install aiscan
+      - run: aiscan scan --type prompt prompts/ --fail-on high
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      - run: aiscan scan --output sarif --out results.sarif .
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with: { sarif_file: results.sarif }
+```
+
+### Pre-commit hook
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: aiscan
+        name: AI Security Scanner
+        entry: aiscan scan --no-ai --fail-on critical
+        language: system
+        files: \.(txt|yaml|yml|json|py|js|ts)$
+```
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Passed — no findings at or above `--fail-on` threshold |
+| `1` | Failed — findings found at or above threshold |
+| `2` | Tool error — bad arguments, missing file |
+
+---
+
+## AI provider configuration
+
+Edit `.env`:
+
+```bash
+# Claude (default)
+AI_PROVIDER=claude
+ANTHROPIC_API_KEY=sk-ant-...
+SCANNER_MODEL=claude-sonnet-4-20250514
+
+# OpenAI
+AI_PROVIDER=openai
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4o
+
+# Vertex AI (Gemini)
+AI_PROVIDER=vertex
+VERTEX_PROJECT=your-gcp-project-id
+VERTEX_LOCATION=us-central1
+VERTEX_MODEL=gemini-2.5-flash-001
+```
+
+If the primary provider fails, aiscan automatically retries with the next available one. Use `--no-ai` to skip AI scanning entirely.
+
+---
+
+## Suppressing false positives
+
+Add `# noscan` (or `// noscan` for JS/TS) to the end of any line to skip it:
+
+```python
+result = scanner.scan_prompt("test example string")  # noscan
+```
+
+---
+
+## Sample files
+
+The `samples/` directory has bad and clean examples for every scan type — useful for testing and learning what each rule detects.
+
+```bash
+aiscan scan --no-ai samples/prompts/bad_system_prompt.txt
+aiscan scan --no-ai samples/agents/bad_research_agent.yaml
+aiscan scan --no-ai samples/apis/bad_config.yaml
+aiscan scan --no-ai samples/mcp/bad_code_executor.json
+aiscan scan --no-ai samples/integrations/bad_slack_integration.yaml
+aiscan scan --no-ai samples/code/bad_app.py
+```
+
+---
+
+## Troubleshooting
+
+**`aiscan: command not found`**
+```bash
+python -m aiscan.cli --help
+pip install -e .
+```
+
+**AI scan not running**
+```bash
+aiscan scan --no-ai openapi.yaml   # confirms static rules work
+# then check .env has a valid API key
+```
+
+**False positives**
+```bash
+aiscan scan --no-ai file.txt   # isolate static rule hits
+aiscan rules                   # see which pattern triggered
+# add # noscan to suppress a specific line
+```
+
+---
+
+## License
+
+MIT