Lurkr

Lurkr

Find what your agent can touch before you deploy it.

Lurkr is a static, local-only scanner for risky AI-agent and GitHub-workflow capability surfaces. It runs before deployment, does not execute project code, does not make network calls during scan, and redacts sensitive output.

New in v0.4.0

Lurkr now includes a high-severity FastAPI / Starlette BadHost detector:

• Rule: agent.python_fastapi_path_auth_no_host_validation
• Flags middleware that reads request.url.path for path-based security decisions without same-file TrustedHostMiddleware evidence.
• Covers Starlette BadHost risk GHSA-86qp-5c8j-p5mr / CVE-2026-48710, fixed upstream in Starlette 1.0.1.
• See [Detection Scope](#detection-scope) and [Triaging Findings](#triaging-findings).

GitHub Actions

- uses: agentveil-protocol/lurkr@v0.4.0
  with:
    path: "."
    output: lurkr-report.json
    fail-on: high

Omit fail-on for review-only mode. Use SARIF output with GitHub Code Scanning when you want findings in the Security tab.

[Local CLI](#local-cli) | [Privacy & data handling](#privacy--data-handling) | [What a finding looks like](#what-a-finding-looks-like) | [Detection scope](#detection-scope) | [Full Action usage](#use-as-a-github-action) | [Why this exists](#why-this-exists)

---

Local CLI

pip install lurkr
lurkr scan --path . --output report.json
cat report.json

That is the whole flow. The scanner is read-only: it does not modify your files, run your code, or send data over the network.

Python agent detection is enabled for bounded .py source analysis. FastAPI / Starlette middleware detection is enabled for BadHost-style path-auth risk: Lurkr flags security middleware that reads request.url.path without same-file TrustedHostMiddleware evidence. Bounded TypeScript / JavaScript MCP analysis is enabled for canonical Model Context Protocol registerTool handler shapes; see [Detection scope](#detection-scope) for the exact patterns covered.

To fail CI when findings meet a threshold, add --fail-on:

lurkr scan --path . --output report.json --fail-on high

For existing repositories, create a baseline first so CI only fails on new findings:

lurkr scan --path . --save-baseline .lurkr-baseline.json
lurkr scan --path . --baseline .lurkr-baseline.json --fail-on high

Privacy & Data Handling

Lurkr is local-only by design.

• It does not upload source code, manifests, scan reports, findings, paths, or

usage data to AgentVeil.

• It does not make network calls during lurkr scan.
• It does not execute scanned project code.
• It writes output only to the terminal or to the report path you provide.
• Reports are redacted: raw secrets, command bodies, private-key bytes, and

credential material are not included.

If you use the optional GitHub Action, the scan still runs inside your CI environment. Any SARIF upload is performed by GitHub's own CodeQL upload action only when you add that step to your workflow.

What a Finding Looks Like

{
  "rule_id": "workflow.deploy_without_approval",
  "severity": "high",
  "file": ".github/workflows/deploy.yml",
  "line": 12,
  "message": "Deployment workflow appears to run without an approval gate.",
  "remediation": "Add a protected GitHub environment or explicit manual approval before production deploy, release, or publish steps."
}

Every finding contains rule ID, severity, repository-relative file path, line number when available, redacted message, and remediation pointer. Raw secrets, command bodies, and key material never appear in the report.

Detection Scope

All current rules are reported as high severity.

| Rule | What it flags | Scope | |---|---|---| | bypass.direct_github_token | Direct GitHub PAT/token references in workflows or agent manifests | GitHub Actions, agent manifests | | workflow.deploy_without_approval | Deploy/release/publish steps without an approval gate | GitHub Actions | | workflow.pull_request_target_secrets_risk | pull_request_target workflows that combine privileged context with checkout, run, or secrets | GitHub Actions | | tool.shell_without_approval | Agent tool manifests that enable shell execution without an approval flag | MCP/CrewAI-style manifests | | identity.private_key_unencrypted | Unencrypted PEM private key files committed to the repo | Repository files | | agent.credential_to_llm_context | Credential-bearing values passed into LLM completion context | OpenAI, Anthropic, Gemini, LangChain direct call sites | | agent.declared_vs_imported_delta | Python AND TypeScript/JavaScript MCP tool registrations not declared in agent manifest files | MCP, CrewAI, AutoGen, LangChain manifests + supported Python tool registrations + bounded TS/JS MCP registerTool shapes | | agent.dynamic_prompt_from_user_input | Prompt templates directly interpolating function parameters | Prompt-shaped Python assignments and common template helpers | | agent.python_api_key_hardcoded | API-key-shaped string literals in Python source | Module-wide; Anthropic, OpenAI, GitHub PAT, HuggingFace | | agent.python_eval_exec_in_tool | eval/exec-style dynamic execution inside Python tool functions | Supported Python tool functions | | agent.python_subprocess_in_tool | Subprocess or shell calls inside supported Python tool functions | Supported Python tool functions | | agent.python_tool_without_approval | Python agent tool declarations without an approval marker | LangChain, LangGraph, CrewAI, MCP, OpenAI tool calling, Anthropic tool use, LlamaIndex, Gemini | | agent.python_unrestricted_file_access | File write or delete calls inside Python tool functions | Supported Python tool functions | | agent.python_fastapi_path_auth_no_host_validation | FastAPI / Starlette middleware reading request.url.path without same-file TrustedHostMiddleware evidence | FastAPI / Starlette HTTP middleware | | agent.unverified_mcp_endpoint | MCP server URLs pointing to non-allowlisted external hosts | MCP manifests | | agent.javascript_child_process_in_tool | Node.js child_process commands inside canonical MCP registerTool handlers (TS/JS) | Canonical MCP registerTool handlers in TS/JS | | agent.javascript_file_mutation_in_tool | Node.js fs / fs/promises write/delete calls inside canonical MCP registerTool handlers (TS/JS) | Canonical MCP registerTool handlers in TS/JS | | agent.javascript_env_secret_access_in_tool | Secret-like process.env. reads inside canonical MCP registerTool handlers (TS/JS) | Canonical MCP registerTool handlers in TS/JS | | agent.javascript_network_call_in_tool | Outbound network calls (fetch / axios / got / undici / http(s)) inside canonical MCP registerTool handlers (TS/JS) | Canonical MCP registerTool handlers in TS/JS |

TS/JS coverage is bounded to canonical Model Context Protocol registerTool registration patterns (identifier-bound, chained, typed helper-wrapper parameters, namespace-qualified, parenthesized) reached through bounded same-file AST analysis and relative-path cross-file handler resolution. See the per-rule docs for each rule's exact gate.

Deployment checks include common CLI deploy, release, registry push, and infrastructure apply commands. Build, plan, dry-run, and package-only commands are excluded unless the same step also contains a deploy marker.

How Lurkr is different

Most AI-agent scanners focus on installed components, MCP servers, prompts, or skills.

Lurkr focuses on capability risk before deployment.

It scans the repo surfaces that turn an agent into an actor:

• GitHub workflows that can deploy or expose secrets
• Agent manifests that expose shell-capable tools
• Python agent code that wires tools to subprocess, file writes, eval/exec, direct tokens, LLM context, prompts, or external MCP endpoints
• Bounded TypeScript / JavaScript MCP tool handlers that reach child_process, file mutation, secret-like process.env, or outbound network calls

Static. Local-only. Offline. Redacted by default.

The goal: find high-severity capabilities worth controlling before they become production incidents — not produce a giant list of theoretical issues.

| Most scanners | Lurkr | |---|---| | MCP servers / installed components | Repo surfaces about to be deployed | | Prompt injection / prompt risk | Risky agent capabilities | | Long lists of potential issues | Conservative high-severity rules | | API tokens / cloud calls | Local, offline, no telemetry | | Generic secrets | Agent-relevant credentials and bypass paths | | Report only | Findings mapped to remove / restrict / redact controls | | Ad-hoc detection logic | Rules grounded in Saltzer-Schroeder principles (1975), Schneier attack trees (1999), OWASP LLM Top 10, MITRE ATLAS |

Roadmap

Available now

19 high-severity rules across:

• GitHub workflows + agent manifests + identity files
• Python agent code: LangChain / LangGraph, CrewAI, MCP (FastMCP and Server-style), OpenAI tool calling, Anthropic tool use, LlamaIndex, Gemini
• FastAPI / Starlette middleware that can make path-based auth decisions from host-poisoned request.url.path
• Bounded TypeScript / JavaScript MCP tool handlers: child_process, fs / fs/promises mutation, secret-like process.env, and outbound network calls (fetch / axios / got / undici / http(s)). Coverage is limited to canonical Model Context Protocol registerTool registration shapes and bounded same-file + relative-import handler resolution
• Declared-vs-imported capability delta across MCP/CrewAI/AutoGen/LangChain manifests, Python tool registrations, AND bounded TS/JS MCP registerTool extraction (identifier-bound, chained, typed helper-wrapper parameters, namespace-qualified, parenthesized, with same-file top-level const name resolution)
• AI-specific static checks for credential flow into LLM context, direct prompt interpolation, and external MCP endpoints
• Baseline mode for CI adoption: save current findings, then fail only on new findings

v0.5.0 — broader framework coverage

Candidates for broader framework coverage:

• AutoGen / AG2 (re-validation against current Microsoft direction)
• PydanticAI
• Semantic Kernel

v0.6.0+ — quality and ergonomics

Roadmap items being considered:

• Auto-fix patches via SARIF fixes field
• Per-finding contextual remediation
• Suppression comments / inline lurkr: ignore
• Cross-file Tool(func=external_module.helper) resolution
• More manifest formats (mcp.json variants)

Community input welcome

Open an issue with framework or rule requests. Real-world examples accelerate prioritization.

Install

From PyPI (recommended)

pip install lurkr

From GitHub release

pip install git+https://github.com/agentveil-protocol/lurkr@v0.4.0

From source (development)

git clone https://github.com/agentveil-protocol/lurkr
cd lurkr
pip install -e .

Docker

docker build -t lurkr .
docker run --rm -v "$PWD:/workspace" lurkr --output /workspace/report.json

The container runs as a non-root user (UID 1000). For host UID/GID matching to avoid permission issues with the generated report file:

docker run --rm -u $(id -u):$(id -g) -v "$PWD:/workspace" lurkr --output /workspace/report.json

Add --fail-on high to make the container exit non-zero when high findings are present.

Use as a GitHub Action

Use the action from the same repository:

- uses: agentveil-protocol/lurkr@v0.4.0
  with:
    path: "."
    output: lurkr-report.json
    fail-on: high

The action requires Python 3.10 or newer on the runner. It writes the report path to the report output and does not upload data to AgentVeil. Omit fail-on to keep review-only behavior.

For existing repositories, commit a baseline and only fail on new findings:

- uses: agentveil-protocol/lurkr@v0.4.0
  with:
    path: "."
    output: lurkr-report.json
    baseline: ".lurkr-baseline.json"
    fail-on: high

For GitHub Code Scanning, write SARIF and upload it with CodeQL:

- uses: agentveil-protocol/lurkr@v0.4.0
  with:
    path: "."
    output: lurkr.sarif
    format: sarif

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: lurkr.sarif

Pre-commit Hook

Run Lurkr as a pre-commit hook to catch capability issues before they reach the remote.

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/agentveil-protocol/lurkr
    rev: v0.4.0
    hooks:
      - id: lurkr
        args: ["--fail-on", "high"]

Then install:

pre-commit install

The hook generates lurkr-report.json on every commit. Omit args for review-only behavior, or use --fail-on to block commits when findings meet the selected threshold.

Triaging Findings

lurkr flags capability surfaces: places where an AI agent or workflow has direct capability to do something risky. Most findings are review items, not incidents:

• bypass.direct_github_token commonly appears on stale-bots,

release-bots, CI publish steps, and label-management workflows that legitimately use the auto-injected secrets.GITHUB_TOKEN. The rule fires by design: the workflow holds direct GitHub write capability and that is a capability surface worth surfacing, even when expected.

• workflow.deploy_without_approval may flag deploy paths that have

approval mechanisms the static scanner cannot see, such as manual job dispatch, branch protection, or external reviewer chains. Verify against your actual approval flow before treating as incident.

• workflow.pull_request_target_secrets_risk flags risky combinations,

but some pull_request_target work

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agentveil-protocol
• Source: agentveil-protocol/lurkr
• License: MIT
• Homepage: https://agentveil.dev

Install and usage instructions live in the source repository linked above.