Security Workbench

Security Workbench is a CLI workbench for repeatable security artifact tasks: parse, transform, normalize, review, and export.

Security Workbench is intended to grow from a CLI workbench into a shared runtime for evidence-backed skills and registered workflows. Future adapters such as REST API, local web UI, and MCP should reuse that runtime path rather than becoming separate analysis engines.

The current build is intentionally local and deterministic. Routine artifacts such as encoded blobs, URLs, headers, JSON, CSV, YAML, Dockerfiles, GitHub Actions workflows, scanner outputs, JWTs, and manifests should be parsed and normalized before deciding whether AI or external enrichment is needed.

artifact or text blob
  → parse / transform
  → extract useful structure
  → review supported signals
  → score review attention
  → generate draft finding output

Current status

Implemented:

TypeScript monorepo
pnpm workspace
packages/schemas
packages/core
plugins/core-utilities
plugins/core-parsers
plugins/plugin-network-registries
plugins/plugin-mac-oui
plugins/core-reviewers
plugins/core-scoring
plugins/core-output
apps/cli
single-skill registry and runner
registered workflow registry and runner
workflow definition validation
CLI workflows list / run
runtime policy enforcement
safe bounded --input-file handling
runtime redaction helpers
shared safe pretty-output rendering
first-party workflow display models
fixture-backed smoke script

Current interface:

CLI only

Not implemented yet:

plugin manifest loader
plugin install commands
external enrichment
REST API
web UI
MCP server
local persistence

Install

Install dependencies:

pnpm install

Install the local checkout as the security-workbench CLI command:

pnpm cli:install-local

For development without installing the global command, use the repo-local shortcut:

pnpm sw workflows list --format table

Common commands

Discovery:

security-workbench help
security-workbench list
security-workbench skills list
security-workbench workflows list --format table

Run a single skill:

security-workbench skills run json_parse --input '{"ok":true}'

Run a registered workflow:

security-workbench workflows run jwt_review \
  --input-file fixtures/jwt/alg-none.jwt \
  --format pretty

For task-oriented commands, see docs/USE_CASES.md and docs/recipes/README.md.

Output formats

Security Workbench supports both machine-readable and human-readable output.

--format json    complete structured run output; source of truth for automation
--format pretty  bounded human-readable view for CLI review and manual QA

JSON output is the authoritative contract for automation, chaining, tests, and future API/web/MCP adapters. It preserves the complete run envelope, runtime metadata, skill output, warnings, and errors.

Pretty output is presentation only. It is rendered through the shared output-view path in this order:

1. plugin-provided output.display model
2. existing skill-specific CLI renderer for retained legacy/simple skills
3. common structured fallback for artifact/observed/signal shapes
4. flat key/value fallback for simple primitive outputs
5. sanitized compact JSON fallback

Registered workflow final outputs should provide authored output.display models so humans do not have to read raw nested JSON. The current registered workflows are covered by first-party display models:

browser_extension_review     -> generate_browser_extension_finding
static_analysis_triage       -> generate_static_analysis_triage_summary
certificate_review           -> review_certificate
jwt_review                   -> review_jwt
sbom_review                  -> review_sbom
package_manifest_review      -> review_package
lockfile_review              -> review_package

Display models are declarative presentation data. Plugins return rows, bullet sections, and bounded tables; the CLI validates and renders them safely. Display content is treated as untrusted. The renderer does not execute commands, read files, fetch URLs, expand templates, import callbacks, render raw HTML, or create clickable links. Rendered strings are bounded, sanitized, redacted, and defanged before they are written to the terminal.

For plugin author guidance, see docs/plugins/README.md and docs/plugins/MAINTENANCE.md.

Current completed chains

The first registered artifact-to-finding workflow is browser extension permission review:

parse_browser_extension_manifest
  → review_browser_extension_permissions
  → score_browser_extension_risk
  → generate_browser_extension_finding

The second registered workflow is static-analysis triage:

parse_sarif
  → review_static_analysis_results
  → score_static_analysis_attention
  → generate_static_analysis_triage_summary

Additional registered parser-to-reviewer workflows cover unambiguous local review chains:

parse_pem_certificate
  → review_certificate

parse_jwt
  → review_jwt

parse_sbom
  → review_sbom

parse_package_json
  → review_package

parse_lockfiles
  → review_package

Additional local chain examples are available as individual skill runs:

lookup_ip_prefix_membership_local
  → review_prefix_membership

lookup_asn_membership_local
  → review_asn_membership

Detailed behavior lives in the core parser, reviewer, scoring, and output plugin docs.

Validation

pnpm build
pnpm test
pnpm typecheck:test
./security-workbench-full-smoke.sh

Smoke can also be run by explicit section when validating an isolated area:

./security-workbench-full-smoke.sh --list-sections
./security-workbench-full-smoke.sh --section plugin:network-registries

Security scanning

Security Workbench has a Semgrep baseline for local SAST validation. The baseline focuses on implementation findings and intentionally excludes fixture/test artifacts that contain synthetic attacker-shaped inputs.

See docs/SECURITY_MODEL.md for the Semgrep command, expected result, and exclusion rationale.

Documentation

• docs/ENGINEERING.md — runtime, repo layout, implementation rules
• docs/ROADMAP.md — current backlog and implementation order
• docs/SECURITY_MODEL.md — trust boundaries, privacy, exposure, output safety
• docs/FIXTURES.md — fixture policy and inventory
• docs/USE_CASES.md — quick map from artifact to command
• docs/recipes/README.md — copy/paste workflow recipes
• docs/plugins/README.md — plugin and skill inventory
• docs/plugins/*.md — per-plugin behavior and limits

Security posture

Default posture:

network disabled unless explicitly enabled
persistence disabled unless explicitly enabled
redaction enabled by default
external binaries denied by default
plugin-owned filesystem access denied by default
API/web/MCP exposure not implemented

Local means control-owned: artifacts stay inside the user's security boundary until external analysis is explicitly justified.