Why I built this

Last week our security guy asked me which systems my AI agents actually have access to. I didn't have a good answer. So I built Heron — now he can ask the agent himself.

The alternative to Heron is a Google Doc that nobody updates. The doc is wrong the day it's written, because the agent's permissions evolve and nobody goes back to fix the doc.

Heron interviews the agent directly. The agent answers about itself — what systems it touches, what data it handles, what permissions it has, what happens when something goes wrong. You get a structured audit report with risk scoring, findings, and a permissions delta showing what the agent has versus what it actually needs.

I tested it on a real content pipeline agent. Heron found 9 connected systems, 1 critical issue (an unauthenticated local HTTP worker), 4 high-severity findings, and 2 scopes that can be safely revoked right now. Total time: about 5 minutes from one command.

No SDK integration. No code changes to the agent. Works with any agent that speaks the OpenAI API.

Try it: npx heron-ai

┌──────────┐         ┌──────────────┐         ┌──────────────┐
│          │         │              │         │              │
│  Agent   │────────>│    Heron     │────────>│ Audit Report │
│          │         │              │         │              │
│          │<────────│  Structured  │         │  Findings    │
└──────────┘         │  Interview   │         │  Systems     │
                     │  (10 core +  │         │  Regulatory  │
                     │  follow-ups) │         │  Verdict     │
                     └──────────────┘         └──────────────┘

Who this is for

Security engineers approving agent deployments. Your dev team wants to ship a new agent. You need to know what it touches before you sign off. Run npx heron-ai, get a structured report with findings, risk score, and a permissions delta. Faster than a Google Doc, harder to fake than a verbal walkthrough.

Platform and DevOps leads inheriting agents from other teams. You just got handed three agents from a team that left. You don't know what they do. Heron interviews them in about 5 minutes and tells you which production systems they touch and which OAuth scopes they hold. Map your blast radius before you have to defend it.

Compliance and audit teams preparing evidence packages. Heron generates regulator-ready reports with EU AI Act, GDPR, SOC 2, and UK GDPR mappings — based on what the agent actually does, not a generic checklist. Attach to your control evidence.

Founders and tech leads asked "is this safe?" by a customer. You're selling an AI feature into a regulated buyer. They ask for an access review. You don't have one. Heron gives you a structured artifact you can hand them in 5 minutes instead of writing one from scratch.

Quick Start

Three ways to use Heron, depending on your setup.

Option 1: Local CLI (open source)

One command. No install, no config, no env vars. The CLI prompts for your LLM API key on first run.

npx heron-ai

An interactive menu lets you choose between two modes:

  Heron — AI Agent Auditor

  > Start server    agents connect to you
    Scan an agent   you connect to an agent

Mode A: Server (heron-ai serve)

Heron runs locally and waits for agents to connect. Two ways to point your agent at it:

1) Paste a prompt into your agent's chat — works with any agent

I need you to complete a security access review for this project.
Make sequential API calls to the Heron endpoint until it says "Interview complete".

Step 1 — Start the interview:
POST http://localhost:3700/v1/chat/completions
Body: {"model":"any","messages":[{"role":"user","content":"Hi, I am ready to answer questions about this project."}]}

The response will contain a question and a session ID (in the "heron_session_id" JSON field).

Step 2 — Send each answer:
POST http://localhost:3700/v1/chat/completions
Body: {"model":"any","messages":[{"role":"user","content":"YOUR ANSWER HERE"}],"heron_session_id":"SESSION_ID_FROM_STEP_1"}

Step 3 — Repeat step 2 until the response says "Interview complete".

Important: answer about THIS specific project — what you actually do, what systems
you connect to, what data you handle. Not general capabilities. Never reveal actual
secret values — just describe credential types.

2) Override OPENAI_BASE_URL — zero code changes to the agent

OPENAI_BASE_URL=http://localhost:3700/v1 python your_agent.py

The agent thinks it's talking to GPT. Heron intercepts, runs the interview, generates the report.

Mode B: Scan (heron-ai scan)

Heron connects directly to your agent's chat API and runs the interview itself.

npx heron-ai scan --target http://your-agent/v1/chat/completions

Option 2: Hosted version (no setup)

Sign in at https://heron.ing and paste this into your AI agent's chat:

I need you to complete a security access review for this project.
Make sequential API calls to the Heron endpoint until it says "Interview complete".

Step 1 — Start the interview:
POST https://heron.ing/v1/chat/completions
Body: {"model":"any","messages":[{"role":"user","content":"Hi, I am ready to answer questions about this project."}]}

The response will contain a question and a session ID (in the "heron_session_id" JSON field).

Step 2 — Send each answer:
POST https://heron.ing/v1/chat/completions
Body: {"model":"any","messages":[{"role":"user","content":"YOUR ANSWER HERE"}],"heron_session_id":"SESSION_ID_FROM_STEP_1"}

Step 3 — Repeat step 2 until the response says "Interview complete".

Important: answer about THIS specific project — what you actually do, what systems
you connect to, what data you handle. Not general capabilities. Never reveal actual
secret values — just describe credential types.

Reports save to your dashboard automatically. Sign in with Google, no credit card, free.

Option 3: Claude Code skill (zero setup)

If you use Claude Code, install the /heron-audit skill:

bash Heron/skills/heron-audit/install.sh

Then in any project:

/heron-audit

Claude interviews itself about the current project and generates an audit report. No server, no API key, no setup.

How It Works

Step 1 — Start Heron

One command. Interactive menu or direct flags.

$ npx heron-ai

  Heron — AI Agent Auditor

  > Start server    agents connect to you
    Scan an agent   you connect to an agent

Step 2 — Agent connects

Heron speaks OpenAI-compatible API. No SDK, no code changes needed.

# Paste the prompt into agent's chat
# Or redirect the base URL:
OPENAI_BASE_URL=http://localhost:3700/v1 \
  your-agent start

Step 3 — Structured interview

10 core questions, each targeting a compliance field. Smart follow-ups probe vague answers. Format examples guide the agent to give concrete, structured responses.

Heron: "List every system you connect to.
       Format: Name → API type → Auth method
       Example: Google Sheets → REST API → OAuth2"

Agent: "HubSpot → REST API → OAuth2
        PostgreSQL → Direct TCP → Password
        Slack → Bot API → Bot token"

Step 4 — Report generated

Per-system access cards, findings with IDs, risk scoring, regulatory flags, and actionable recommendations.

  Audit complete: sess_abc123
  Risk:         MEDIUM
  Data quality: 100/100
  Verdict:      APPROVE WITH CONDITIONS
  Findings:     4
  Report:       ./reports/sess_abc123.md
  Dashboard:    http://localhost:3700/sessions/sess_abc123

Interview Protocol

10 structured questions targeting compliance fields, plus LLM-generated follow-ups:

| # | Question | Compliance Field | |---|----------|-----------------| | 1 | Deployment profile (project name, owner, trigger) | Agent identity | | 2 | Permissions and scopes per system | Scopes requested | | 3 | Systems enumeration (Name → API → Auth) | System inventory | | 4 | Data sensitivity per system (PII/financial/confidential) | Data sensitivity | | 5 | Detailed permissions | Access assessment | | 6 | Data read operations and classification | Data inventory | | 7 | Reversibility of operations | Reversibility | | 8 | Write operations (Action → Target → Reversible? → Volume) | Write operations | | 9 | Blast radius (records/users affected if write fails) | Blast radius | | 10 | Frequency and volume (runs/week, API calls/run) | Frequency & volume | | + | Unused permissions, worst-case failure, decision-making about people | Excess access, risk, regulatory |

Follow-ups are generated when answers are vague or compliance fields are missing (up to 6 per interview).

Report Structure

1. Executive Summary — dashboard table (risk / systems / findings)
2. Agent Profile — purpose, trigger, owner, frequency
3. Findings — severity-ranked with IDs (HERON-001, ...), split description and recommendation
4. Systems & Access — per-system cards with risk rating, scopes, data, writes, blast radius
5. What's Working Well — positive findings
6. Verdict & Recommendations — APPROVE / APPROVE WITH CONDITIONS / DENY
7. Regulatory Compliance — EU (AI Act + GDPR), US (SOC 2 + state AI laws), UK (UK GDPR + ICO)
8. Data Quality — field-by-field coverage score, repeated answer warnings
9. Interview Transcript — full Q&A for manual review

Example Report

View full example report →

A real audit of an educational content pipeline agent — reads lessons from Google Sheets, generates Russian content with Gemini, creates Google Docs and slide decks, publishes to an LMS. The report covers 9 connected systems, 1 critical and 4 high-severity findings, per-system access cards, regulatory flags (GDPR, SOC 2, EU AI Act), and a verdict with actionable recommendations.

Two Modes

| Mode | Command | Direction | Use Case | |------|---------|-----------|----------| | Server | serve | Agent → Heron | Deploy as a gate. Agents connect to Heron | | Scan | scan | Heron → Agent | Connect to an agent's API and interrogate it |

LLM Provider

Heron auto-detects the provider from your API key:

| Key prefix | Provider | Default model | |------------|----------|---------------| | sk-ant- | Anthropic | claude-sonnet-4 | | sk- | OpenAI | gpt-5.4-mini | | AIza | Gemini | gemini-2.0-flash |

The CLI prompts for your key on first run, or you can pass it via env var:

export HERON_LLM_API_KEY=sk-xxx   # optional — provider and model auto-selected

Override with --llm-provider and --llm-model if needed.

Reference

npx heron-ai serve [options]

| Flag | Description | Default | |------|-------------|---------| | -p, --port <port> | Port to listen on | 3700 | | -H, --host <host> | Host to bind to | 0.0.0.0 | | --llm-key <key> | LLM API key | HERON_LLM_API_KEY env | | --llm-provider <p> | anthropic, openai, or gemini | auto-detect | | --llm-model <model> | Analysis LLM model | auto per provider | | --max-followups <n> | Max follow-up questions | 3 | | --report-dir <dir> | Where to save reports | ./reports |

API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /v1/chat/completions | POST | OpenAI-compatible — agents connect here | | /api/sessions | GET | List all sessions (JSON) | | /api/sessions/:id | GET | Session details + transcript | | /api/sessions/:id/report | GET | Download audit report (markdown) | | / | GET | Dashboard |

npx heron-ai scan [options]

| Flag | Description | Default | |------|-------------|---------| | -t, --target <url> | Agent's chat API URL | required | | --llm-key <key> | LLM API key | HERON_LLM_API_KEY env | | --llm-provider <p> | anthropic, openai, or gemini | auto-detect | | --llm-model <model> | Analysis LLM model | auto per provider | | -o, --output <path> | Save report to file | ./reports/scan_xxx.md | | --max-followups <n> | Max follow-up questions | 3 | | --report-dir <dir> | Where to save reports | ./reports |

Architecture

bin/heron.ts              CLI entry point (interactive menu, scan, serve)
src/
  server/
    index.ts              HTTP server + dashboard + OpenAI-compatible endpoint
    sessions.ts           Session manager with follow-ups and async analysis
  interview/
    questions.ts          10 structured questions (one per compliance field)
    protocol.ts           Interview flow: greeting skip, repeat detection, follow-ups
  analysis/
    analyzer.ts           LLM transcript analysis with Zod validation + retry + fallback
    risk-scorer.ts        Rubric-driven risk scoring from structured per-system data
  report/
    generator.ts          Regulatory compliance flags (EU/US/UK) + report assembly
    templates.ts          Markdown report: per-system cards, findings, positive findings
    types.ts              Zod schemas for SystemAssessment, AuditReport, RegulatoryFlags
  llm/
    client.ts             Unified LLM client (Anthropic/OpenAI/Gemini, auto-detect)
    prompts.ts            Interview + analysis prompts with anti-hallucination rules
  connectors/             Agent connection (HTTP, interactive)
  config/                 YAML config loading + Zod validation

Development

git clone https://github.com/theonaai/Heron.git
cd Heron && npm install

# Run locally
npx heron-ai serve

# Tests
npm test

Contributing

Issues and PRs welcome.

Contact

Questions, feedback, ideas? Reach out:

• LinkedIn: Ilya Ivanov
• Telegram: @Ilya_Ivanov0

License

MIT