mirror of
https://github.com/BradGroux/veritas-kanban.git
synced 2026-10-08 12:47:51 +00:00
101 lines
3.6 KiB
Markdown
101 lines
3.6 KiB
Markdown
# Skill Security Scanner
|
|
|
|
The v5 skill security scanner is a static first-pass review for local skills. It
|
|
accepts a skill directory or a single `SKILL.md`, returns structured JSON, and
|
|
persists JSON plus Markdown reports under
|
|
`.veritas-kanban/skill-security-scans/` unless `persist` is `false`.
|
|
|
|
## When to Run It
|
|
|
|
Run the scanner before installing or updating a skill that contains scripts,
|
|
assets, package manifests, broad trigger language, network access, credential
|
|
handling, persistence hooks, durable memory behavior, or tool/runtime
|
|
instructions.
|
|
|
|
```bash
|
|
curl -X POST http://localhost:3001/api/skills/security/scan \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"path":"/absolute/path/to/skill","persist":true}'
|
|
```
|
|
|
|
Maintenance callers can use the equivalent admin-only action:
|
|
|
|
```http
|
|
POST /api/maintenance/skill-security/scan
|
|
```
|
|
|
|
## Risk Inventory and Workflow Gates
|
|
|
|
Persisted scans feed the shared skill risk inventory:
|
|
|
|
```http
|
|
GET /api/skills/security/inventory
|
|
```
|
|
|
|
The inventory is shown in Settings -> Shared Resources -> Skill Risk Dashboard.
|
|
It combines shared skill metadata, declared-vs-observed capability mismatches,
|
|
latest scan summaries, remediation task links, and temporary exceptions.
|
|
|
|
Install decisions are intentionally conservative:
|
|
|
|
- `allow`: no blocking risk or an active reviewed exception.
|
|
- `warn`: medium or caution risk that needs acknowledgement.
|
|
- `block`: high, critical, or `do-not-install` risk.
|
|
|
|
Workflow authoring dry-runs include a `skillAudit` summary for `skill:<id>` and
|
|
`skill/<id>` references found in agents, tools, steps, variables, inputs, and
|
|
descriptions. Local workflows warn on unscanned skills; remote and cloud
|
|
workflows block unscanned, missing, or blocked skills unless an active exception
|
|
exists.
|
|
|
|
## Detector Scope
|
|
|
|
The scanner currently detects:
|
|
|
|
- Prompt injection through instruction overrides, hidden comments, and
|
|
zero-width text.
|
|
- Exfiltration through remote egress, remote script fetch/execute, and
|
|
file-to-network combinations.
|
|
- Credential harvesting through env, token, API key, keychain, password, and
|
|
authorization references.
|
|
- Unsafe execution through shell, subprocess, eval, and dynamic code patterns.
|
|
- Persistence through cron, launch agents, daemons, watchers, background jobs,
|
|
self-modification, and durable memory writes.
|
|
- Memory poisoning and overbroad trigger rules.
|
|
- Declared capability mismatches by reusing the skill capability profile model.
|
|
- Unpinned or non-registry dependencies where statically detectable from
|
|
package manifests.
|
|
|
|
This is not a full sandbox or dependency vulnerability audit. Treat `safe` as
|
|
"no configured static pattern fired", not as proof that a skill is harmless.
|
|
|
|
## Artifacts
|
|
|
|
Every persisted scan writes:
|
|
|
|
- `<scan-id>.json`: structured report with files, findings, severity, risk
|
|
score, recommendation, capability profile, and redacted evidence.
|
|
- `<scan-id>.md`: human-readable review report for PRs or maintenance notes.
|
|
- Audit event `skill.security.scan.completed` with scan id, severity, risk
|
|
score, recommendation, and finding count.
|
|
|
|
Evidence snippets are redacted with the same string redactor used by server
|
|
logs. Fixtures intentionally use placeholder secret-like strings and assert that
|
|
raw placeholder values do not appear in reports.
|
|
|
|
## Fixture Contract
|
|
|
|
Fixtures live in `server/src/__fixtures__/skill-security/`.
|
|
|
|
Each fixture includes:
|
|
|
|
- `SKILL.md`
|
|
- optional `scripts/`, `assets/`, or package manifests
|
|
- `expected.json` with expected findings, absent findings, max severity,
|
|
recommendation, and optional redaction assertions
|
|
|
|
Run the fixture gate:
|
|
|
|
```bash
|
|
pnpm --filter @veritas-kanban/server test -- skill-security-service.test.ts
|
|
```
|