agentsec-ai 0.5.0

Security scanner for AI agents and MCP servers. OWASP Agentic Top 10 mapping, SARIF output, CI/CD ready.

agentsec

Static configuration scanner and hardener for AI agent installations. Detects misconfigurations, credential leaks, supply-chain risks, and MCP tool poisoning — then maps every finding to the OWASP Top 10 for Agentic Applications (2026).

Supports OpenClaw, Claude Code, Cursor, Windsurf, Gemini CLI, and MCP server ecosystems.

Scope: agentsec performs static configuration and file analysis. It does not provide runtime protection, behavioral monitoring, or real-time threat detection. Use as one layer in a defense-in-depth strategy.

Quick Start

pip install agentsec-ai
agentsec scan

Scan a specific installation:

agentsec scan ~/.openclaw

What agentsec checks

Module	Scope
installation	Gateway exposure, auth posture, DM/group policy, tool/sandbox settings, SSRF and safety checks, known CVE version checks, sensitive file/dir permissions
skill	Instruction malware, risky code patterns (eval/exec/subprocess), prompt-injection patterns, frontmatter capability risk, dependency/install-hook risk
mcp	Tool poisoning patterns, auth gaps on remote endpoints, dangerous schema/permissions, unverified npx usage
credential	detect-secrets engine (23 plugins) + 16 custom patterns (OpenAI, Anthropic, AWS, Databricks, HuggingFace, Groq, Mistral, etc.), high-entropy detection, git credential leakage

Reference catalog:

• Checks Catalog (33 named checks + dynamic credential findings)
• CLI Reference (full command/options guide)

Core Commands

# Full installation scan (all scanners, default target=. )
agentsec scan

# JSON report for CI parsing and pipelines
agentsec scan -o json -f report.json

# SARIF output for GitHub code scanning upload
agentsec scan -o sarif -f results.sarif

# Run only selected scanners for focused checks
agentsec scan -s installation,mcp

# Fail build only at/above selected severity
agentsec scan --fail-on critical

# Preview profile changes without writing config
agentsec harden -p workstation

# Apply profile and write hardened config values
agentsec harden -p workstation --apply

# Watch files and auto re-scan on security-relevant changes
agentsec watch ~/.openclaw -i 2

# Pre-install package gate (scan before install)
agentsec gate npm install express

# Pin MCP tool descriptions for rug-pull detection
agentsec pin-tools

# Generate shell hook wrappers for npm/pip install flows
agentsec hook --shell zsh

List available scanners (names + descriptions):

agentsec list-scanners

Hardening Profiles

Profile	Intended use
workstation	Single-owner local usage
vps	Remote/self-hosted deployment
public-bot	Highest restriction for untrusted public input

Use agentsec show-profile <name> to inspect exact changes before applying.

Output and Exit Codes

Output formats:

• terminal (default)
• json
• sarif

Exit codes:

• 0: no findings at/above threshold
• 1: findings found at/above threshold
• 2: usage error (e.g., unknown scanner name)
• 3: runtime error (e.g., file access failure)

GitHub Actions

Use the bundled composite action:

name: Agent Security
on: [push, pull_request]

jobs:
  agentsec:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: debu-sinha/agentsec@v0.4.5
        with:
          fail-on: high
          output: sarif
          upload-sarif: 'true'

Action definition:

• action.yml

Screenshots

Screenshots below show the experimental demo sandbox flow (intentionally insecure configuration for detection and hardening demonstration). Gate and hook behavior are documented in docs/case-studies/003-preinstall-gate-blocked-malicious-package.md and docs/adr/ADR-0004-pre-install-gate.md.

Step 1: Initial scan on intentionally insecure demo config

Step 2: Apply workstation hardening profile

Step 3: Re-scan findings after hardening

Step 4: OWASP posture view after hardening

MCP Ecosystem Security Dashboard

Weekly automated security scan of the top 50 MCP server repositories, graded A through F.

View the full dashboard - updated every Monday via GitHub Actions.

Benchmarks and Studies

• Fixture benchmark — precision/recall/F1 over a 20-fixture suite (self-authored fixtures, not independently validated).
• Top-50 MCP study — agentsec-only repro run with normalized findings output.
• Top-50 study kit — schema, selection CSV, JSONL findings, and summary JSON.

Current checked-in Top-50 summary data:

• docs/benchmarks/top50/reports/top50_summary_20260215.json
• docs/benchmarks/top50/reports/top50_findings_20260215.jsonl

Reproducibility

Fixture benchmark:

python docs/benchmarks/run_benchmark.py

Top-50 study repro:

powershell -ExecutionPolicy Bypass -File scripts\reproduce_top50_study.ps1 -DateStamp 20260215

Note: semgrep and gitleaks baseline runs are optional in the PowerShell repro script and require those tools on PATH.

Adversarial consistency audit (docs vs artifacts):

python scripts/repo_consistency_audit.py

Case Studies

• 001: Insecure workstation remediation
• 002: Public bot hardening on VPS
• 003: Pre-install gate blocked malicious package
• 004: Malicious skill detection and block

Launch Evidence

• Launch Evidence Manifest
• Reproducibility Spec

Development

git clone https://github.com/debu-sinha/agentsec.git
cd agentsec
pip install -c requirements/constraints-dev.txt -e ".[dev]"
ruff check src tests
pytest

Contribution guide:

• CONTRIBUTING.md

Security policy:

• SECURITY.md

Governance

• Code of Conduct
• Security Policy
• Contribution Guide

Issue intake is template-driven under .github/ISSUE_TEMPLATE/ to keep triage and reproduction quality high.

License

Apache-2.0