-lightgrey){kind=icon}
Language / 语言： English · 简体中文
One-click local scans for your AI agents — exposure risks, dependency CVEs, and MCP / Skills assets. Everything stays on your device.
v0.1 early preview — Actively evolving; UI and APIs may change. Issues and PRs welcome.
AgentSec is a macOS-first desktop security scanner built for Hermes and OpenClaw. It does not replace your agents; it runs a local health check: surface misconfigurations and risky skills, match dependencies against known CVEs, and let you manage MCP servers, Skills, knowledge bases, and packages in one place — no cloud, no telemetry, no account.
| Platform | Status | Notes |
|---|---|---|
| macOS | ✅ Primary | Day-to-day dev and ./scripts/package-dmg.sh releases |
| Windows | 🧪 Experimental | package-win.ps1 and path abstractions exist; scanning not fully validated — feedback welcome |
| Typical security tools | AgentSec | |
|---|---|---|
| What it scans | Processes, containers | Agent configs, Skills, MCP, dependencies |
| Risk coverage | CVEs, ports | Exposure + injection rules + CVE in parallel |
| How you use it | CLI / server-side | One-click desktop scan, revisitable results |
| Your data | Often uploaded | Stays on your device, redacted snapshots only |
Exposure detection — pyATR rule packs plus OpenClaw security audit for agent-specific risks: baseline drift, prompt injection, tool-description poisoning, and context exfiltration. Findings aggregate by source and rule ID with severity tiers, evidence snippets, file locations, and ignore / path-whitelist workflows.
Vulnerability management — OSV-backed correlation between dependency versions and known CVEs, rolled up per component with CVSS, blast radius, and fix versions. Exposure and CVE pipelines are decoupled: a failed CVE feed does not block exposure results.
Asset discovery & response — Hermes / OpenClaw adapters inventory local MCP servers, skills, knowledge bases, and package dependencies per agent. Supports update, disable, and uninstall with configurable confirmation gates.
Permission posture — Normalizes declared permissions from agents and attached assets across file, shell, network, tool, and knowledge-base categories; a permission matrix compares capability coverage per component, and radar charts compare agents to spot over-privileged or risky capability mixes.
Unified operations — Fleet-wide security score, remediation queue, and per-agent workbench tie together threat review, CVE tracking, and asset ops without switching between separate scanners and config tools.
Local trust boundary — Scan, persist, and render entirely on-device. Snapshots are redacted for credential-like fields before storage. No telemetry and no cloud account required.
Download the latest release for your platform — no Node.js or Python required.
| Platform | Download | Notes |
|---|---|---|
| macOS | GitHub Releases → AgentSec-*.dmg |
Open the DMG and drag AgentSec to Applications |
| Windows | Same page → AgentSec Setup *.exe |
Experimental — scanning not fully validated |
macOS DMG builds are currently unsigned. If Gatekeeper blocks the app, allow it under System Settings → Privacy & Security, or right-click the app → Open.
After install, launch AgentSec and run a scan from the home screen. Results and preferences are stored locally (macOS: ~/Library/Application Support/AgentSec/). Language, theme, CVE lookup, and other options are in the in-app Settings page.
For contributors or testing unreleased changes. Requires Node.js ≥ 18 and Python ≥ 3.10.
AgentSec is two parts: engine/ is the Python scan backend; app/ is the Electron desktop shell. In dev mode the shell spawns the engine from engine/.venv.
Run commands from the repository root.
macOS ships with
python33.8, which is too old. Do not runpython3 -m venvinsideengine/if you already have anengine/.venvbuilt with 3.11 — that triggersensurepiperrors.
./scripts/setup-engine.sh # once: Python venv + engine deps
./scripts/run-dev.sh # Electron dev (hot reload)If engine/.venv already exists with Python 3.10+, skip straight to ./scripts/run-dev.sh.
Slow Electron downloads:
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"Scanning and packaging on Windows are not fully validated — feedback welcome via Issues.
In PowerShell (Python 3.10+ on PATH; use py -3.11 if python points to an older version):
cd engine
python -m venv .venv # remove .venv first if recreate fails
.\.venv\Scripts\Activate.ps1
pip install -e .
cd ..\app
npm install
npm run devDiscovery defaults to %USERPROFILE%\.hermes and %USERPROFILE%\.openclaw. Report Issues if paths or behavior differ from macOS.
Slow Electron downloads:
$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"The PyInstaller-frozen Python engine must be built on the target OS (you cannot produce a runnable Windows .exe engine from macOS alone). Package the Electron shell on each platform separately; use the repo scripts below.
macOS (DMG) — on macOS:
./scripts/package-dmg.sh| Flag | Purpose |
|---|---|
--skip-engine |
Skip PyInstaller (faster when the engine unchanged) |
--skip-npm-install |
Skip npm install |
Output: app/release/AgentSec-*.dmg · icon: app/build/icon.icns
Windows (NSIS · experimental) — PowerShell from the repo root on Windows:
.\scripts\package-win.ps1| Flag | Purpose |
|---|---|
-SkipEngine |
Skip PyInstaller |
-SkipNpmInstall |
Skip npm install |
Output: app/release/AgentSec Setup *.exe (app/build/icon.ico is not shipped yet; falls back to the electron-builder default icon)
Manual steps (from app/):
npm run build:engine # runs ../scripts/build-engine.cjs on the current OS
npm run build # TypeScript + Vite + Electron main
npm run dist:mac # electron-builder → dmg
npm run dist:win # electron-builder → NSIS (run on Windows)Mirror for electron-builder binaries (optional):
ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"
| Component | Role | Notes |
|---|---|---|
| pyATR | Exposure rules | Bundled ATR rule packs, offline matching |
| OSV | CVE lookup | Network query for dependency CVEs (graceful degradation) |
| cvss | CVSS parsing | Severity display |
| OpenClaw security audit rules | Exposure supplement | Parallel to pyATR; see engine/agentsec_engine/detectors/ |
UI stack: Electron · React · Vite · TypeScript.
Issues and PRs welcome. Before UI changes: cd app && npx tsc --noEmit
Copyright © 2026 ChuhC. Licensed under AGPL-3.0. Network-deployed modifications must offer corresponding source to users.
Report security issues via SECURITY.md and GitHub Security Advisories — do not file public Issues for exploitable vulnerabilities.