PatronAI

Open-source AI endpoint monitoring for shadow AI, ghost AI, and unmanaged model usage.

PatronAI helps security, platform, and AI governance teams discover unknown AI endpoints, detect abandoned AI assets, and monitor model usage across applications, agents, cloud services, and developer environments.

It ingests VPC Flow Logs, Packetbeat, and Zeek telemetry, normalises to OCSF, and matches against a deny-all list of 70+ AI providers. A code-scanning layer (Marauder Scan) detects AI framework imports (LangChain, CrewAI, AutoGen, 40+ others), MCP server registrations, and hardcoded API keys at git commit time. An on-prem AI chat assistant (LFM2.5-1.2B-Thinking via llama.cpp) answers questions over your findings — data never leaves your environment.

Single Docker container. Multi-cloud. Grafana dashboards pre-built and provisioned on first boot. Apache 2.0.

• Outbound calls to 70+ AI provider domains (OpenAI, Anthropic, Cohere, Mistral, Groq, Stability AI, Replicate, Together AI, HuggingFace, Bedrock, Vertex AI, Azure OpenAI, …)
• Calls to any domain on the customer deny list (config/unauthorized_custom.csv)

• AI framework imports — LangChain, LlamaIndex, CrewAI, AutoGen, Haystack, DSPy, Semantic Kernel, Instructor, Guidance, and 40+ others
• MCP server registrations — reads Claude Desktop, Cursor, Continue, Cline JSON config files; fires MCP_CONFIG_CHANGED when a config changes
• Agent workflows — n8n, Flowise, langflow JSON/YAML files sitting on disk
• Hardcoded API keys — OpenAI sk-proj-, Anthropic sk-ant-, HuggingFace hf_, and generic bearer token patterns
• Vector databases — Chroma, FAISS, LanceDB, Qdrant, Milvus files in home caches or repos

flowchart TD
    subgraph edge["Edge — developer devices"]
        hook["Git pre-commit hook\n(Marauder Scan)"]
        scan["Endpoint scan\nevery 30 min"]
        hb["Heartbeat\nevery 5 min"]
    end

    subgraph net["Network layer"]
        vpc["VPC Flow Logs"]
        pb["Packetbeat / Zeek"]
    end

    subgraph s3["S3 — single source of truth"]
        ocsf["ocsf/ raw events"]
        findings["findings/ YYYY/MM/DD/"]
        config["config/\nprovider lists + settings"]
    end

    subgraph platform["PatronAI — single Docker container"]
        scanner["Scanner engine\nNormalise → Match → Alert"]
        dash["Streamlit UI\nExec · Manager · Support · Home"]
        grafana["Grafana\ndashboards"]
        llm["LFM2.5-1.2B-Thinking\nchat LLM (llama.cpp)"]
    end

    hook -->|OCSF event| ocsf
    scan -->|OCSF event| ocsf
    hb  -->|OCSF event| ocsf
    vpc -->|OCSF event| ocsf
    pb  -->|OCSF event| ocsf

    ocsf   --> scanner
    config --> scanner
    scanner --> findings
    scanner -->|SNS / webhook| alerts["Alerts\n(SNS · Slack · PagerDuty)"]
    findings --> dash
    findings --> grafana
    dash <-.->|AI chat · tool calls| llm

Data never leaves your cloud account. All telemetry writes to your own S3 bucket; the scanner reads from S3 every scan cycle; no third-party cloud plane.

Marauder Scan is PatronAI's discovery layer for hidden AI usage. It maps AI activity across source code, configuration files, MCP definitions, API calls, provider domains, network telemetry, and deployed endpoints to help teams find shadow AI, ghost AI assets, and unmanaged model usage.

In short: PatronAI is the platform; Marauder Scan is the mapping and discovery engine inside it.

Before you start — 3 things to know:

• Email-only login. PatronAI has no password field. Add your email to ALLOWED_EMAILS in .env and that becomes your login credential.
• First-boot LLM download. On first docker compose up, PatronAI auto-downloads LFM2.5-1.2B-Thinking (~750 MB) into a Docker volume. The dashboard opens immediately; AI chat activates once the download finishes (~3-5 min on a typical EC2 connection).
• SNS confirmation email. If you use prereqs.sh, AWS sends a subscription confirmation to ADMIN_EMAILS. You must click it — if you miss it, alert emails are silently dropped with no error logged.

Requires: Docker Desktop + an existing S3 bucket (or LocalStack).

git clone https://github.com/giggsoinc/patronai.git
cd patronai/ghost-ai-scanner

cp .env.example .env
# Open .env and fill in the 5 REQUIRED lines:
#   PATRONAI_BUCKET, COMPANY_NAME, COMPANY_SLUG, ADMIN_EMAILS, ALLOWED_EMAILS

docker compose up -d
open http://localhost:8501   # macOS — or navigate in any browser

Log in with any email you added to ALLOWED_EMAILS. No password required.

Run unit tests first (optional, ~40 s, no Docker needed):

pip install -r requirements.txt
cd .. && pytest ghost-ai-scanner/tests/unit/ -q
# → 380 passed

Full local guide: docs/quickstart-local.md

Run all commands from the repo root (patronai/).

# Step 1 — Deploy EC2, transfer code, install Docker + LLM
bash deploy_to_ec2.sh

# Step 2 — SSH in when the script finishes, then run interactive setup
#   (creates S3 bucket, SNS topic, IAM role + policy, VPC Flow Logs, writes .env)
bash prereqs.sh

# Step 3 — Start the stack  (3 containers: patronai, grafana, nginx)
docker compose up -d

# Step 4 — Populate ENI metadata cache (run once after first deploy)
docker exec patronai python3 scripts/refresh_eni_cache.py

# Teardown — removes EC2, S3, SNS, IAM, VPC Flow Log
bash teardown.sh

Bucket variable: PATRONAI_BUCKET is the canonical name going forward. MARAUDER_SCAN_BUCKET is accepted as a backward-compatible alias (existing deployments do not need to change). Both are passed through docker-compose.yml.

All settings are also writable from the Streamlit Settings tab. Values persist to s3://{bucket}/config/settings.json and apply within one scan cycle.

PatronAI applies a 5-type ENI denylist before normalisation to eliminate noise:

Only ENIs where RequesterManaged=False and OwnerId matches the customer account are normalised. ENI metadata cached in S3, refreshed every 6 hours. Cache miss = fail open — unknown ENIs are never silently dropped.

Add new ENI types without code changes: config/eni_denylist.yaml.

Lists reload on every scan cycle — no container restart needed. Invalid rows are rejected at write time by src/matcher/rule_model.py (same validation runs in the UI and the scanner).

Discovered AI tools queue — the Provider Lists tab surfaces novel AI domains that hit the network in the last 7 days ranked by event count. Admins promote to deny list (one click) or dismiss.

Findings from the code layer are aggregated into the Manager → AI INVENTORY tab:

• MCP servers — name, command, args, env-var keys (no values)
• Agent workflows — n8n, Flowise, langflow files on developer machines
• Scheduled agents — cron / launchd entries mentioning AI keywords
• Vector databases — Chroma, FAISS, LanceDB, Qdrant, Milvus
• Tool registrations — @tool / @function_tool decorator counts (no source shipped)

All findings pass through the secret redactor before upload. Findings that still contain secrets after redaction are dropped entirely.

Click any owner in the AI INVENTORY tab → AI Asset Mind Map (radial graph, drill filter on click) and Asset Map (treemap: Owner → Repo → Category → Asset).

Admins generate personalised installers from Settings → Deploy Agents:

1. Enter recipient name, email, and platform (Mac / Linux / Windows).
2. Optionally set per-user authorised tool domains.
3. Click Generate & Send — renders OTP-locked .sh + .ps1, builds macOS DMG and Windows EXE on EC2 (no Mac or Windows machine needed), emails a 48-hour presigned download link + 6-digit OTP to the recipient.
4. Status updates from PENDING → INSTALLED as agents check in.
5. Update any user's tool whitelist without reinstalling: Whitelist button in table.

Install (Mac/Linux):

curl -fsSL "<presigned-link-from-email>" | bash
# Enter 6-digit OTP when prompted

Diagnose:

bash ~/.patronai/diagnose.sh      # macOS / Linux
powershell -File ~/.patronai/diagnose.ps1   # Windows

s3://{bucket}/
├── config/
│   ├── authorized.csv               customer allow list
│   ├── unauthorized.csv             Giggso baseline deny (overwritten on deploy)
│   ├── unauthorized_custom.csv      customer additions (survives rebuilds)
│   ├── unauthorized_code.csv        code-layer baseline
│   ├── unauthorized_code_custom.csv code-layer customer additions
│   └── HOOK_AGENTS/
│       ├── catalog.json             index of all provisioned agents
│       └── {token}/
│           ├── meta.json            recipient metadata + expiry
│           ├── setup_agent.sh       macOS/Linux installer
│           ├── setup_agent.ps1      Windows installer
│           └── status.json          install status (PENDING → INSTALLED)
├── ocsf/YYYY/MM/DD/                 incoming OCSF normalised events
├── ocsf/agent/scans/{token}/        latest endpoint scan per agent
├── findings/YYYY/MM/DD/
│   ├── critical.jsonl
│   ├── high.jsonl
│   ├── medium.jsonl
│   └── unknown.jsonl
├── summary/daily/                   pre-aggregated stats (dashboards read from here)
└── chat/{sha256(email)[:16]}/{view}/YYYY-MM-DD.jsonl   AI chat history

Two pre-built dashboards provisioned on first boot:

• Exec — AI governance: bubble chart, world map, MCP topology, risk heatmap
• Manager — Inventory, risks, raw OCSF browser, alerts

Every dashboard view includes a persistent 🤖 Ask PatronAI side panel. Powered by llama.cpp running LiquidAI LFM2.5-1.2B-Thinking (Q4_K_M, ~750 MB) on the same EC2 host — no data leaves your environment. Backed by per-user / per-tenant hourly S3 rollups so answers cite real data with S3 paths, not LLM hallucinations. BM25 retrieval over the HTML+MD docs answers product/how-to questions.

Supports tool calls for 10 analytics + help functions:

get_summary_stats · get_top_risky_users · get_user_risk_profile · query_findings · get_fleet_status · get_shadow_ai_census · get_recent_activity · compare_periods · get_help · refresh_docs

Pluggable LLM: set LLM_PROVIDER=anthropic or point LLM_BASE_URL at any OpenAI-compatible endpoint (Ollama, Groq, Together AI, LM Studio). API keys read from env vars or AWS Parameter Store (/patronai/llm/*).

MCP server (scripts/patronai_mcp_server.py) — exposes the same 8 analytics tools to Claude Desktop and any MCP-compatible agent over SSH stdio (V1, no HTTP port).

All outbound email goes through one module — src/notify/email.py — which is the single SES call site for the codebase. Any new feature that needs to send email imports from here:

from notify.email import send, send_welcome, send_agent_otp, send_alert, ensure_verified

Three convenience wrappers compose subject + body for each domain:

All three call notify.email.send() underneath, which (a) resolves SES_SENDER_EMAIL (or legacy PATRONAI_FROM_EMAIL) → falls back to patronai@<company>.com with a WARN log; (b) calls ensure_verified() on every recipient unless auto_verify=False so SES sandbox mode unblocks itself as new users are added; (c) logs the boto3 ErrorCode on failure so the next time something breaks you can grep notify.email and read the cause.

For background SNS / webhook alerts on HIGH and CRITICAL findings see ALERT_SNS_ARN, TRINITY_WEBHOOK_URL, and LOGANALYZER_WEBHOOK_URL in ghost-ai-scanner/.env.example.

SES sandbox warning: new SES accounts can send only to verified recipients (200/day cap). The notify.email.send() path auto-verifies recipients, but they still have to click AWS's verification email before subsequent sends to them succeed. Long-term fix: request SES production access in the AWS Console → SES → Account dashboard. ~24h approval, removes the sandbox constraint entirely.

Where to find things. This index is the source of truth — keep it up to date when you add or move modules.

Companion artifacts (machine-readable):

• CODE_MAP.csv — every file with path, layer, purpose, key_exports, depends_on, notes. Greppable, AI-tool-ingestable.
• Roadmap.csv — backlog: P0/P1/P2/OPS items + done log with id, title, category, priority, effort, status, owner, target_release, notes.
• docs/codebase-tree.html — printable visual tree of the same content (open in browser).

patronai/
├── README.md                                 # this file
├── SECURITY.md                               # vulnerability reporting policy
├── SECURITY_CONSIDERATIONS.md                # production hardening checklist
├── docs/
│   ├── quickstart-local.md                   # local Docker setup
│   ├── github-metadata.md
│   ├── launch-issues.md
│   └── archive/                              # superseded HTML guides (Mac agent guide is here)
└── ghost-ai-scanner/                         # the actual product
    ├── main.py                               # container entrypoint — spawns scanner / chat / rollup / streamlit threads
    ├── docker-compose.yml                    # 3 services: scanner, grafana, nginx
    ├── Dockerfile / Dockerfile.grafana
    ├── requirements.txt                      # all Python deps, license-pinned
    ├── iam-policy.json                       # AWS IAM policy for the runtime role
    │
    ├── src/                                  # business logic
    │   ├── bootstrap.py                      # validate_env, build_store, load_settings
    │   ├── threads.py                        # scanner_loop, alerter_backlog, url_refresh_loop, streamlit_proc
    │   ├── code_analyser.py                  # AMBIGUOUS-snippet classifier (llama-cli subprocess)
    │   ├── code_fallback.py                  # regex fallback when classifier is offline
    │   ├── rule_health.py                    # validate merged rule counts
    │   │
    │   ├── normalizer/                       # event flattening + provider-name normalisation
    │   │   ├── schema.py                     # OCSF flat schema definition
    │   │   ├── agent_explode.py              # agent payload → flat findings
    │   │   └── provider_names.py             # raw provider → human name (e.g. claude.ai → "Anthropic Claude")
    │   │
    │   ├── matcher/                          # network-side rule engine
    │   ├── alerter/dispatcher.py             # SNS + Trinity webhook fan-out
    │   ├── ingestor/                         # S3-walk → pipeline → findings store
    │   │
    │   ├── store/                            # S3 persistence layer (BlobIndexStore)
    │   │   ├── base_store.py                 # SigV4-forced boto3 client
    │   │   ├── findings_store.py             # findings/YYYY/MM/DD/{sev}.jsonl
    │   │   ├── agent_store.py                # OTP-gated agent installer packages
    │   │   ├── users_store.py                # users/users.json — RBAC source of truth
    │   │   └── …                             # cursor, dedup, identity, report, summary, settings
    │   │
    │   ├── jobs/                             # background workers spawned from main.py
    │   │   ├── hourly_rollup.py              # findings → per-user / per-tenant dimension rollups
    │   │   └── docs_refresh.py               # mtime-watch the docs RAG index
    │   │
    │   ├── query/                            # read-side helpers for chat tools
    │   │   └── rollup_reader.py              # parallel S3 GETs + dimension-aware merge + LRU
    │   │
    │   ├── chat/                             # LLM agent (the "brain") — used by widget AND MCP server
    │   │   ├── engine.py                     # tool-call loop
    │   │   ├── tools.py                      # 8 analytics tools
    │   │   ├── tools_schema.py               # JSON schemas
    │   │   ├── prompts.py                    # system prompt builder
    │   │   ├── help.py                       # get_help + refresh_docs
    │   │   ├── docs_index.py                 # BM25 over docs/**/*.{md,html}
    │   │   ├── history.py                    # S3 chat-history persistence + lifecycle policy
    │   │   └── llm/                          # provider-agnostic transport
    │   │       ├── __init__.py               # factory: env / SSM → client
    │   │       ├── base.py                   # LLMClient ABC
    │   │       ├── openai_compat.py          # llama.cpp / Ollama / OpenAI / Groq
    │   │       └── anthropic.py              # Anthropic Messages API
    │   │
    │   └── notify/                           # SINGLE email surface for the codebase
    │       ├── __init__.py                   # public re-exports
    │       └── email.py                      # send() / send_welcome / send_agent_otp / send_alert / ensure_verified
    │
    ├── dashboard/                            # Streamlit UI (entry: ghost_dashboard.py)
    │   ├── ghost_dashboard.py
    │   ├── auth.py / auth_gate.py            # email-allowlist auth (SSO is roadmap)
    │   └── ui/
    │       ├── chat/widget.py                # ONLY chat code in dashboard/ — Streamlit panel
    │       ├── manager_tab_*.py              # Manager view tabs (inventory, risks, actions, …)
    │       ├── exec_tab_*.py / support_tab_*.py
    │       ├── tabs/users.py                 # Users RBAC CRUD — calls notify.email.send_welcome
    │       ├── tabs/deploy_agents.py         # Agent OTP packages — calls render_agent_package
    │       └── …
    │
    ├── scripts/                              # operator scripts (NOT business logic)
    │   ├── setup.sh                          # interactive first-run setup (creates AWS infra + .env)
    │   ├── start.sh                          # safe `docker compose up` wrapper (env-shadow guard, STS verify)
    │   ├── prefetch_model.sh                 # populate /models named volume before container start
    │   ├── deploy_to_ec2.sh                  # SCP code → EC2 + remote install
    │   ├── render_agent_package.py           # OTP + presigned URL + DMG/EXE builder; calls notify.email.send_agent_otp
    │   ├── patronai_mcp_server.py            # FastMCP exposure of chat tools to Claude Desktop / Cursor
    │   └── …
    │
    ├── config/                               # default rules + provider lists (CSV / YAML)
    ├── agent/                                # hook-agent fragment templates (sh + ps1)
    ├── grafana/ · nginx/                     # provisioning + reverse-proxy
    ├── tests/                                # 397 unit tests + integration suite
    └── docs/                                 # active product docs (HTML + MD)
        ├── architecture_chat_mcp.html        # chat + MCP architecture deep-dive
        ├── user_guide.html                   # end-user dashboard guide
        ├── patronai-agent-{linux,windows}-guide.html
        ├── chat-rollups.md                   # how the per-tenant hourly rollups work
        ├── vpc_flow_filtering.md
        └── archive/                          # superseded versions of older guides

One-rule guideline: if you're about to write a boto3.client("ses") call, stop and use notify.email instead. If your new feature needs something notify.email doesn't have, extend that module — don't fork.

# Unit tests only (~40 seconds, no Docker/LocalStack needed)
cd ghost-ai-scanner
pytest tests/unit/ -q
# → 380 passed

# Full suite including integration
bash scripts/run_regression.sh          # unit + integration + docker build
bash scripts/run_regression.sh --unit-only

380 tests across 38 files covering normaliser, matcher, alerter, code engine, agent delivery, endpoint scan, fleet heartbeat, chat tools, pipeline health, and more.

CLOUD_PROVIDER=aws    # default
CLOUD_PROVIDER=gcp    # implements providers/gcp/ adapter
CLOUD_PROVIDER=azure  # implements providers/azure/ adapter

Four scenarios not fully detectable (documented for transparency):

1. Fully offline local inference — model on disk, data copied via USB. The endpoint scan detects the installed package and running process, but not the data movement itself.
2. Personal cloud accounts — personal AWS/GCP with personal credit card. Out of scope for the network layer.
3. Web UI manual copy-paste — partially mitigated by browser history check.
4. Personal laptop outside VPN — unmanaged device; accepted organisation risk.

Contributions are welcome! See CONTRIBUTING.md for:

• Local setup and test instructions
• Coding standards (150 LOC cap per file, type hints, try/except on every external call)
• How to add a new AI provider to the deny list
• PR checklist

Quick contribution path — add a new AI provider:

# 1. Add a row to config/unauthorized.csv or config/unauthorized_code.csv
# 2. The rule_model validates automatically — no code change needed
# 3. Submit a PR with evidence (URL, API pattern, risk category)

Please do not open a public GitHub issue for security vulnerabilities.

Report privately: security@giggso.com

See SECURITY.md for the full disclosure policy and supported versions.

Apache License 2.0 — © 2026 Giggso Inc / Ravi Venugopal

Open-source dependencies: