Agentsec

Audit AI agent skills for security vulnerabilities. Use when scanning installed skills against the OWASP Agentic Skills Top 10, checking skills before runnin...

Security Scan

Agentsec's requirements and instructions match its purpose as a local skill-auditing CLI, but it will read many user skill directories and runs code from the npm registry when invoked via npx, so review the published package and limit scan scope if you need tighter privacy.

Purpose & Capability

The skill's name, description, and runtime instructions all describe a tool that audits agent skills. The declared anyBins (agentsec, npx, bunx) and the node install spec for the 'agentsec' npm package are proportionate and expected for a CLI auditing tool.

Instruction Scope

SKILL.md instructs you to run 'npx agentsec' which auto-discovers and scans many skill directories (user home, project folders, platform-specific paths, and /etc for some platforms). Reading those directories and files is expected for an auditor, but it is broad (potentially touches many personal and system files). There is no instruction to exfiltrate results to external endpoints; reports are generated locally.

Install Mechanism

Installation/run guidance uses npm/bun (npx or global install). This is a standard mechanism but npx will fetch and execute code from the npm registry at runtime — a moderate-risk operation compared with an instruction-only skill. The install does not use arbitrary URLs or archives, and the package comes from the npm ecosystem (traceable), not a personal server.

Credentials

No secrets or credentials are requested (requires.env is empty), which is appropriate. SKILL.md references OPENCLAW_PROFILE for locating OpenClaw profiles, but this environment variable is not declared in the metadata — a minor inconsistency that should be documented. No hidden credentials or unrelated environment variables are required.

Persistence & Privilege

The skill does not request always: true and does not declare elevated platform-wide privileges. Autonomous invocation is allowed (default), which is normal for skills. The tool's ability to read many directories is a functional requirement rather than an unexplained privilege request.

Scan Findings in Context

[no_code_files_to_scan] expected: This skill is instruction-only (SKILL.md only). The regex-based scanner had no code files to analyze; however, runtime behavior depends on the npm 'agentsec' package that will be fetched/executed when you run npx.

Assessment

Agentsec appears coherent for its stated purpose, but be aware of three practical risks before running it: (1) npx agentsec will download and execute the 'agentsec' package from the npm registry at runtime—review the package (author, versions, changelog) and prefer a pinned version or inspect the package contents before executing; (2) the tool auto-discovers and reads many skill directories (home, project, and system paths). If you want to limit exposure, run with --path to target a specific directory or run in a confined environment/container; (3) SKILL.md references OPENCLAW_PROFILE but doesn't declare it—if you use that environment variable, know it can influence which paths are scanned. Recommended steps: inspect the npm package source or homepage (https://agentsec.sh), run the first scan in a sandbox or CI runner with limited access, use --path/--platform flags to narrow scope, and prefer installing a known-good pinned version instead of unpinned npx invocation.

agentsec is a security auditing CLI for AI agent skills. It scans every skill installed in a project against the OWASP Agentic Skills Top 10 and reports vulnerabilities, misconfigurations, and governance gaps.

When to Use

Use agentsec when the user asks to:

• Audit, scan, or check agent skills for security issues
• Verify installed skills are safe before running them
• Check OWASP compliance of an agent setup
• Gate a CI/CD pipeline on skill security
• Generate a security report for stakeholders

Quick Start

The fastest path to a result — no install, no flags:

npx agentsec

This scans every default skills directory on the machine — grouped by platform — plus any ./skills folder in the current project (up to two levels deep), and audits each installed skill against the OWASP Agentic Skills Top 10. Always try this first.

Auto-discovery locations

Platform	Paths scanned
Claude Code	~/.claude/skills, ./.claude/skills, ~/.claude/plugins/*/skills/*, ~/.claude/commands, ./.claude/commands
OpenClaw / ClawHub	~/.openclaw/workspace/skills, ~/.openclaw/workspace-*/skills (profiles via OPENCLAW_PROFILE), ~/.openclaw/skills
Codex / skills.sh	~/.agents/skills, ./.agents/skills, ../.agents/skills, /etc/codex/skills
Other (generic)	Any skills/ directory found within the current project, up to two levels deep

Core Commands

Every workflow starts from one of four commands. Run them with npx agentsec — no install needed.

# Full audit (scan + policy evaluation). Default command.
npx agentsec

# Scan only (no policy evaluation)
npx agentsec scan

# Generate a report from a previously saved audit JSON
npx agentsec report audit.json

# Manage and inspect policy presets
npx agentsec policy list

Installation

npx agentsec needs no install. For repeated use, install globally:

# bun (recommended)
bun add -g agentsec

# npm
npm install -g agentsec

# pnpm
pnpm add -g agentsec

# yarn
yarn global add agentsec

Then drop the npx prefix:

agentsec
agentsec scan --path ./my-skills

Flags

All flags work with any command.

Flag	Short	Values	Default	Purpose
--format	-f	text, json, sarif, html	text	Output format
--output	-o	path	stdout	Write report to file
--policy	-p	preset name or path	default	Apply a policy preset
--platform		openclaw, claude, codex	auto	Narrow to one agent platform
--path		path	auto	Custom skill directory to scan
--verbose	-v		off	Show detailed findings
--no-color			off	Disable colored output
--help	-h			Show help
--version	-V			Print version

Common Recipes

Show detailed findings and remediation

npx agentsec --verbose

Scan a specific directory

npx agentsec scan --path ./my-skills

Target a specific agent platform

npx agentsec --platform claude
npx agentsec --platform codex

Audit with a strict policy and save JSON

npx agentsec --policy strict --format json --output audit.json

Generate an HTML report for stakeholders

npx agentsec --format html --output report.html

Generate a SARIF report for IDE / code-scanning integration

npx agentsec --format sarif --output report.sarif

List available policy presets

npx agentsec policy list

Inspect the rules in a preset

npx agentsec policy show strict

Validate a custom policy config file

npx agentsec policy validate ./my-policy.json

Replay a previous audit as an HTML report

npx agentsec report audit.json --format html --output report.html

Policy Presets

Name	Use Case
default	Balanced policy. Blocks critical findings.
strict	Enterprise-grade. Blocks high and critical findings, enforces tests.
permissive	Lenient. Only blocks critical CVEs. Good for development.
owasp-agent-top-10	Built directly from the OWASP Agentic Skills Top 10.

Configuration File

agentsec auto-loads .agentsecrc, .agentsecrc.json, or agentsec.config.json from the current directory (or any parent):

{
  "format": "text",
  "output": null,
  "policy": "strict",
  "verbose": false
}

CLI flags always override config file values. Omit "platform" and "path" to keep the default auto-discovery behavior — agentsec will scan every known platform's default locations.

OWASP Agentic Skills Top 10

Every audit checks all ten risk categories:

ID	Risk
AST01	Malicious Skills
AST02	Supply Chain Compromise
AST03	Over-Privileged Skills
AST04	Insecure Metadata
AST05	Unsafe Deserialization
AST06	Weak Isolation
AST07	Update Drift
AST08	Poor Scanning
AST09	No Governance
AST10	Cross-Platform Reuse

Understanding the Output

Default output is compact: each skill shows its grade and score, followed by a one-line finding summary and a PASS/WARN/FAIL status.

✔ Found 6 skills

✔ fetch-data     v1.0.0  D (42)
✔ deploy-helper  v2.3.0  C (68)
✔ code-review    v1.1.0  A (95)

6 skills scanned  •  avg score 78  •  4 certified
Findings: 2 critical, 1 high, 2 medium

⚠ WARN  3 high/critical finding(s) detected

Use --verbose for score breakdowns, rule IDs, file/line locations, and remediation for each finding.

Exit Codes

• 0 — audit passed the active policy
• 1 — policy violation or fatal error

Use the exit code directly to gate CI pipelines — no special flag required:

npx agentsec --policy strict || exit 1

Tips

• Start with npx agentsec — no install, no flags. Iterate from there.
• Add --verbose whenever you need to act on specific findings.
• Pipe --format json into jq or a custom script for programmatic handling.
• strict is the most common preset for production repositories.
• Browse the agent skills ecosystem at skills.sh.