nanoguard 0.1.0
Open-source CLI infrastructure scanner for AI agents
License: MIT
Requires Python: >=3.11
Keywords: security, ai, agents, scanning, vulnerability

# NanoGuard

**Open-source CLI infrastructure scanner for AI agents**

[![CI](https://github.com/nanosec-ai/nanoguard/actions/workflows/ci.yml/badge.svg)](https://github.com/nanosec-ai/nanoguard/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

NanoGuard is a free, open-source command-line tool for scanning AI agent instances and auditing agent skills for security vulnerabilities. Built by [Nanosecond AI](https://nanosec.ai) to help developers secure the emerging AI agent ecosystem.

## Features

- **Instance Scanning** - Detect vulnerabilities in running ClaWDBOT/OpenClaw instances
- **Skill Auditing** - Analyze agent skills for malicious behavior before installation
- **Multi-Engine Analysis** - YARA + Semgrep + LLM heuristic with cross-engine consistency scoring
- **Safe Archive Extraction** - Zip-slip, zip-bomb, and symlink rejection as first-class security invariants
- **SARIF-First CI/CD** - Native GitHub Code Scanning support with stable output schemas
- **SSRF-Hardened** - DNS pinning, private IP rejection, passive-only reconnaissance
- **Zero Service Dependencies** - Runs entirely offline with no external services required (except optional LLM)

## Why NanoGuard

### Competitive Differentiation

- **Multi-engine analysis** — YARA + Semgrep + LLM heuristic with cross-engine consistency scoring
- **Safe archive extraction** — Zip-slip, zip-bomb, and symlink rejection as first-class security invariants
- **SARIF-first CI/CD integration** — Native GitHub Code Scanning support with stable output schemas
- **SSRF-hardened scanner** — DNS pinning, private IP rejection, passive-only reconnaissance
- **Curated CVE database** — Every entry verified against NVD primary sources

### The Problem

Tens of thousands of exposed ClaWDBOT/OpenClaw instances with zero authentication identified by multiple research teams (Censys, Hunt.io, SecurityScorecard STRIKE). Three critical CVE vulnerabilities in versions <2026.1.29. Hundreds of malicious skills identified in ClawHub (Cisco AI Defense, Koi Security). 230+ confirmed malicious skills catalogued as of February 2026 (AuthMind, Cisco AI Defense). No existing security scanner for the AI agent ecosystem.

## Installation

**Requirements:** Python 3.11 or higher

### Basic Installation

```bash
pip install nanoguard
```

### With Optional Dependencies

```bash
# With LLM heuristic support
pip install "nanoguard[llm]"

# With Semgrep AST analysis
pip install "nanoguard[semgrep]"

# With all optional features
pip install "nanoguard[llm,semgrep]"

# Development installation
git clone https://github.com/nanosec-ai/nanoguard
cd nanoguard
pip install -e ".[dev,llm,semgrep]"
```

### Secret Scanning Setup (Development)

For contributors, set up pre-commit hooks:

```bash
# Install gitleaks
brew install gitleaks  # macOS
# or visit: https://github.com/gitleaks/gitleaks#installation

# Configure git hooks
make setup-hooks
```

## Quick Start

### Scan an Agent Instance

```bash
# Basic scan
nanoguard scan https://my-agent:3000

# JSON output
nanoguard scan https://my-agent:3000 --format json

# SARIF for GitHub Code Scanning
nanoguard scan https://my-agent:3000 --format sarif > results.sarif
```

### Audit a Skill

```bash
# Audit directory
nanoguard audit ./my-skill/

# Audit archive
nanoguard audit ./downloaded-skill.zip

# With LLM heuristic analysis
export ANTHROPIC_API_KEY=sk-ant-xxx
nanoguard audit ./my-skill/ --llm

# Filter by severity
nanoguard audit ./my-skill/ --severity high
```

### CI/CD Integration

```yaml
# .github/workflows/security.yml
name: Security Scan

on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install nanoguard
      - run: nanoguard audit ./skills/ --format sarif > nanoguard.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: nanoguard.sarif
```

## Exit Codes

- **0** — No security findings (or unreachable target without `--fail-on-unreachable`)
- **1** — Warnings found (LOW/MEDIUM severity) or unreachable with `--fail-on-unreachable`
- **2** — Critical findings (HIGH/CRITICAL severity) or SSRF rejection
- **3** — Internal error or crash

## CVE Database

NanoGuard includes a curated database of OpenClaw/ClaWDBOT vulnerabilities:

- **CVE-2026-25253** (CVSS 8.8, HIGH) - One-click RCE via token exfiltration
- **CVE-2026-25157** (CVSS 7.8, HIGH) - OS command injection via sshNodeCommand
- **CVE-2026-24763** (CVSS 8.8, HIGH) - Docker sandbox escape via PATH manipulation

All CVEs affect versions <2026.1.29. **Update immediately if running older versions.**

Every CVE entry links to a primary source (NVD or GitHub Advisory). Community contributions welcome via PR with primary source citation.

## Responsible Use

**⚠️ Important:** NanoGuard is designed for authorized security testing only.

- **Scan only systems you own or have explicit written permission to test.**
- The instance scanner uses GET/HEAD requests only (passive reconnaissance).
- Maximum 50 requests per target per scan — no brute-forcing or fuzzing.
- Default SSRF protections deny private, link-local, and cloud metadata IP ranges.
- NanoGuard does not send exploit payloads, inject code, or attempt authentication bypass.

Unauthorized scanning may violate computer fraud laws (e.g., CFAA in the US, Computer Misuse Act in the UK). Always obtain permission before scanning.

## Known Limitations

- **Line numbers in YARA findings are best-effort** and only available for UTF-8 text files. Binary files report byte offsets instead.
- **Semgrep** is a large dependency (400MB+) and made optional. Install separately if needed.
- **LLM heuristic** is advisory only and requires an Anthropic API key. Static analysis (YARA/Semgrep) is always authoritative.

## CLI Reference

### Global Flags

```
--format [text|json|sarif]  Output format (default: text)
--severity [level]          Minimum severity to report
--quiet                     Suppress non-finding output
--no-color                  Disable colored output
--version                   Show version
```

### `nanoguard scan <target>`

Scan an AI agent instance for vulnerabilities.

**Flags:**
- `--fail-on-unreachable` - Exit with code 1 when target unreachable (default: exit 0)

**Examples:**
```bash
nanoguard scan https://agent.example.com:3000
nanoguard scan https://agent.example.com --format json | jq .
nanoguard scan https://agent.example.com --fail-on-unreachable
```

### `nanoguard audit <path>`

Audit an AI agent skill for malicious behavior.

**Flags:**
- `--llm` - Enable optional LLM-based heuristic analysis (requires ANTHROPIC_API_KEY)

**Examples:**
```bash
nanoguard audit ./my-skill/
nanoguard audit ./skill.zip
nanoguard audit ./skill/ --llm --format sarif
```

## Validation Environment

NanoGuard includes scripts to deploy a DigitalOcean-based validation environment with intentionally vulnerable, hardened, and partially-secured AI agent instances.

**Quick Start:**
```bash
# Prerequisites: doctl installed and authenticated
make deploy-validation

# Run scans against deployed instances
nanoguard scan http://<VULN_IP>:3000              # Expect CRITICAL
nanoguard scan https://<HARD_IP>:3000 --insecure  # Expect clean
nanoguard scan https://<PART_IP>:3000 --insecure  # Expect CRITICAL

# Or run automated validation matrix
make validate-matrix

# Teardown when done
make teardown-validation
```

See [deploy/README.md](deploy/README.md) for full documentation.

## Development

### Setup

```bash
git clone https://github.com/nanosec-ai/nanoguard
cd nanoguard
make setup-hooks  # Configure git hooks for secret scanning
make install-dev  # Install with dev dependencies
```

### Running Tests

```bash
make test
pytest tests/ -v --cov=nanoguard
```

### Linting

```bash
make lint
ruff check src/ tests/
```

## Architecture

NanoGuard uses a multi-engine analysis approach:

1. **YARA Engine** - Pattern matching for known malicious behaviors
2. **Semgrep Engine** (optional) - AST-level code analysis
3. **Primitive Detection** - Fast regex pass for common patterns
4. **LLM Heuristic** (optional) - Advisory-only deep analysis
5. **Consistency Scorer** - Cross-engine validation with conflict resolution

Static analysis (YARA/Semgrep) is always authoritative. LLM findings are advisory and never override static results (Invariant I-07).

## Security Invariants

NanoGuard enforces strict security invariants:

- **I-01:** SSRF Prevention - All targets validated against deny list
- **I-02:** Safe Extraction - Archives extracted member-by-member, never `extractall()`
- **I-03:** No Code Execution - Skill code is never executed during analysis
- **I-04:** Symlink Rejection - All symlinks/hardlinks rejected
- **I-05:** Zip-Slip Prevention - Path validation after `realpath()`
- **I-06:** Size Limits - Enforced for compressed, uncompressed, file count, depth
- **I-07:** LLM is Advisory - Static analysis is authoritative
- **I-08:** Consistency Checking - Cross-engine validation with conflict resolution
- **I-09:** Passive Scanning - GET/HEAD only, 50-request budget
- **I-10:** Unreachable ≠ Vulnerability - Availability issues are INFO, not security findings

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

Before submitting a PR:
1. Run `make setup-hooks` to enable secret scanning
2. Ensure all tests pass: `make test`
3. Run linter: `make lint`
4. Add tests for new features

## License

MIT License - see [LICENSE](LICENSE) for details.

## Support

- **Documentation:** [nanoguard.app/docs](https://nanoguard.app/docs)
- **Issues:** [GitHub Issues](https://github.com/nanosec-ai/nanoguard/issues)
- **Security:** See [SECURITY.md](SECURITY.md)

## About Nanosecond AI

NanoGuard is built by [Nanosecond AI](https://nanosec.ai) — "We don't trust agents. We limit them."

Nanosecond AI provides:
- **NanoPay** (nanopay.dev) - Commercial payment infrastructure for AI agents with acceptance, settlement, escrow, and disputes
- **NanoGuard** (nanoguard.app) - Open-source infrastructure scanning (this project)

NanoGuard is optional community tooling that helps developers discover the NanoPay ecosystem. It works independently and requires no NanoPay integration.

---

**Built with ❤️ by the Nanosecond AI team**