Plugins ship skills. Skills are small typed capabilities executed by the runtime.
Current implementation:
packages/core
packages/schemas
plugins/core-utilities
plugins/core-parsers
plugins/plugin-browser-extension
plugins/plugin-certificates
plugins/plugin-network-registries
plugins/plugin-mac-oui
plugins/plugin-url-triage
plugins/plugin-email
plugins/plugin-packages
plugins/plugin-sbom
plugins/core-reviewers
plugins/plugin-scanner-normalize
plugins/core-output
apps/cli
Current interface:
CLI only
Current registered skills:
92 total
38 core-utilities
5 core-parsers
4 plugin-browser-extension
2 plugin-certificates
12 plugin-scanner-normalize
12 plugin-network-registries
4 plugin-mac-oui
3 plugin-url-triage
2 plugin-email
3 plugin-packages
2 plugin-sbom
2 core-reviewers
3 core-output
transform, parser, reviewer, scoring, and output categories
| Package | Skills | Role |
|---|---|---|
plugins/core-utilities |
38 | deterministic transforms and lightweight parser-category utilities |
plugins/core-parsers |
5 | richer generic local artifact/document parsers and shared parser primitives |
plugins/plugin-browser-extension |
4 | browser extension parsing, permission review, deterministic scoring, finding generation, and workflow ownership |
plugins/plugin-certificates |
2 | local PEM certificate parsing, evidence-backed metadata review, and workflow ownership |
plugins/plugin-scanner-normalize |
12 | scanner parsing, normalization, deduplication, merging, summary, and static-analysis triage |
plugins/plugin-network-registries |
12 | local ASN/IP prefix registry parsers, normalization, lookup, and review |
plugins/plugin-mac-oui |
4 | local MAC address parsing, OUI registry snapshot normalization, and local MAC vendor lookup |
plugins/plugin-url-triage |
3 | defanged URL extraction, credential-safe URL parsing, and evidence-backed structural review |
plugins/plugin-email |
2 | local email-header parsing and evidence-backed routing/authentication review |
plugins/plugin-packages |
3 | package manifest and lockfile parsing, evidence-backed package review, and workflow ownership |
plugins/plugin-sbom |
2 | CycloneDX/SPDX parsing, evidence-backed inventory-quality review, and workflow ownership |
plugins/core-reviewers |
2 | deterministic local evidence-backed reviewer skills |
plugins/core-output |
3 | deterministic local finding and export output skills |
base64_decode
base64_encode
base32_encode
base32_decode
url_encode
url_decode
hex_encode
hex_decode
identify_hash
md5_hash
sha1_hash
sha256_hash
sha512_hash
rot13
json_parse
json_format
calculate_entropy
string_normalize
html_entity_decode
unicode_escape_decode
quoted_printable_decode
defang_iocs
refang_iocs
normalize_indicators
extract_iocs
extract_urls
extract_domains
extract_emails
extract_ipv4
extract_hashes
extract_cves
extract_uuids
parse_jwt
trim_lines
remove_empty_lines
dedupe_lines
sort_lines
count_lines
parse_http_headers
parse_dockerfile
parse_github_actions_workflow
parse_csv
parse_yaml
parse_browser_extension_manifest
review_browser_extension_permissions
score_browser_extension_risk
generate_browser_extension_finding
Owned workflow:
browser_extension_review
parse_pem_certificate
review_certificate
Owned workflow:
certificate_review
parse_trufflehog_ndjson
parse_sarif
parse_semgrep_json
parse_checkov_json
parse_grype_json
normalize_scanner_results
dedupe_scanner_results
scanner_summary
merge_scanner_results
review_static_analysis_results
score_static_analysis_attention
generate_static_analysis_triage_summary
Owned workflow:
static_analysis_triage
parse_ip_prefix_list
parse_asn_list
parse_asn_allow_deny_list
parse_asn_observations
parse_bgp_prefix_table
parse_rir_delegated_stats
parse_routeviews_prefix2as_snapshot
normalize_network_registry_snapshot
lookup_ip_prefix_membership_local
lookup_asn_membership_local
review_prefix_membership
review_asn_membership
parse_mac_address_lists
parse_oui_registry_snapshots
normalize_oui_registry_snapshot
lookup_mac_vendor_local
extract_defanged_urls
parse_url
review_url
URL triage remains a recipe-level manual chain. No registered workflow is added by the package-boundary migration.
parse_email_headers
review_email_header
Email-header review remains a recipe-level manual chain. No registered workflow is added by the package-boundary migration.
parse_package_json
parse_lockfiles
review_package
Owned workflows:
package_manifest_review
lockfile_review
parse_sbom
review_sbom
Owned workflow:
sbom_review
review_jwt
review_security_headers
generate_finding
export_markdown
export_json
Registered workflows are runtime definitions that chain existing skills. Workflow behavior is documented in recipes and the owning plugin docs.
| Workflow | Steps | Purpose |
|---|---|---|
browser_extension_review |
parse_browser_extension_manifest → review_browser_extension_permissions → score_browser_extension_risk → generate_browser_extension_finding |
Review a browser extension manifest and generate a draft permission finding. |
static_analysis_triage |
parse_sarif → review_static_analysis_results → score_static_analysis_attention → generate_static_analysis_triage_summary |
Review SARIF scanner output and generate a draft triage summary. |
certificate_review |
parse_pem_certificate → review_certificate |
Review parsed PEM certificate metadata. |
jwt_review |
parse_jwt → review_jwt |
Review parsed JWT header, claim, and signature metadata. |
sbom_review |
parse_sbom → review_sbom |
Review parsed CycloneDX or SPDX SBOM inventory quality. |
package_manifest_review |
parse_package_json → review_package |
Review parsed package manifest metadata. |
lockfile_review |
parse_lockfiles → review_package |
Review parsed package lockfile inventory metadata. |
Pretty output is rendered through the shared output-view path. JSON output remains complete and may include the optional output.display presentation model returned by a skill.
Registered workflow final outputs should provide first-party display models so workflow results are readable without CLI hardcoded workflow-specific renderers. Current coverage:
| Workflow | Final skill | Display title |
|---|---|---|
browser_extension_review |
generate_browser_extension_finding |
Browser Extension Finding |
static_analysis_triage |
generate_static_analysis_triage_summary |
Static-analysis triage summary |
certificate_review |
review_certificate |
Certificate Review |
jwt_review |
review_jwt |
JWT Review |
sbom_review |
review_sbom |
SBOM Review |
package_manifest_review |
review_package |
Package Review |
lockfile_review |
review_package |
Lockfile Review |
Use this rule of thumb when adding plugins:
workflow final output -> provide output.display
complex reviewer output -> provide output.display
simple primitive output -> flat pretty fallback is acceptable
legacy parser view -> existing CLI renderer is acceptable until migrated
Display models are data, not rendering code. A skill should return a declarative DisplayModel with bounded summary rows, sections, bullets, and tables. The CLI owns validation, terminal sanitization, redaction, defanging, truncation, and final formatting. Do not add plugin-specific renderer branches in apps/cli/src/runFormat.ts for new workflow outputs.
A minimal display model looks like:
import type { DisplayModel } from "@security-workbench/schemas";
const display: DisplayModel = {
version: 1,
title: "Example Review",
summary: [
{ label: "Status", value: "review" },
{ label: "Signals", value: 2 },
],
sections: [
{
title: "Signals",
bullets: ["High-risk observation", "Missing expected metadata"],
},
],
};Use DisplayText values when content is artifact-derived or needs explicit treatment:
{
label: "Observed value",
value: {
value: artifactValue,
source: "artifact",
trust: "untrusted_artifact_content",
treatment: "quoted",
},
}Do not put raw secrets, executable markup, terminal escape sequences, callbacks, templates, file paths to read, URLs to fetch, or rendering instructions in a display model.
core-utilities: small deterministic primitives and text/indicator/URL helpers
core-parsers: generic local artifact parsers and parser-category utilities
plugin-certificates: local PEM certificate parsing, metadata review, and workflow ownership
plugin-packages: local package manifest and lockfile parsing, package review, and workflow ownership
plugin-sbom: local CycloneDX/SPDX parsing, inventory-quality review, and workflow ownership
packages/core: generic runtime contracts and shared runtime helpers
packages/schemas: shared schemas, types, and generic evidence/signal structures
reviewer plugins: evidence-backed interpretation
enrichment plugins: explicit external/provider context or local registry context
scoring plugins: prioritization
output plugins: findings and exports
domain plugins: focused first-party or external capability packs
Shared primitive rule:
If a function is required by more than one domain plugin, promote it to core.
Do not create plugin-to-plugin imports between sibling domain plugins.
Do not duplicate shared helper implementations across domain plugins.
Default destinations:
generic runtime contracts -> packages/core
shared schemas and types -> packages/schemas
deterministic text/indicator/URL helpers -> plugins/core-utilities
generic artifact parsers -> plugins/core-parsers
SBOM parsing and inventory review -> plugins/plugin-sbom
generic evidence/signal helpers -> packages/schemas or packages/core
Domain plugin dependency rule:
domain plugins may depend on packages/core, packages/schemas, core-utilities, generic core-parser outputs, and narrow core-output safety helpers
domain plugins should not depend on sibling domain plugins
helpers needed by multiple domain plugins should be promoted, documented as shared primitives, and tested at the core layer
Examples:
CIDR matching used by network registries, CloudFormation, Kubernetes, and Terraform belongs in core-utilities or packages/core.
Defang/refang helpers used by URL triage, email, and indicator utilities belong in core-utilities.
Evidence reference builders used by reviewers and output plugins belong in packages/schemas or packages/core.
MAC normalization used only by MAC/OUI belongs in the MAC/OUI plugin.
ASN normalization used only by network registries belongs in the network-registries plugin.
packages/schemas defines the shared plugin manifest schema contract. It covers plugin identity, package name, version, description, entrypoint declaration, trust tier, quality label, capability modes, permission metadata, exposure declaration, skill declarations, optional workflow declarations, docs path, owned paths, and dependencies.
The manifest schema is a contract only. It does not load plugin code, install packages, enable external execution, or bypass runtime policy.
Official first-party plugin manifests live beside each workspace plugin as plugin.security-workbench.json and are validated against the shared schema in packages/schemas tests. packages/core also provides bounded workspace discovery for these direct-child manifests. Discovery validates UTF-8/JSON, schema shape, entrypoint declarations, runtime entrypoint existence and containment, and duplicate plugin/package/skill identities without loading discovered entrypoints.
Current official manifest files:
plugins/core-utilities/plugin.security-workbench.json
plugins/core-parsers/plugin.security-workbench.json
plugins/plugin-browser-extension/plugin.security-workbench.json
plugins/plugin-certificates/plugin.security-workbench.json
plugins/plugin-scanner-normalize/plugin.security-workbench.json
plugins/plugin-network-registries/plugin.security-workbench.json
plugins/plugin-mac-oui/plugin.security-workbench.json
plugins/plugin-url-triage/plugin.security-workbench.json
plugins/plugin-email/plugin.security-workbench.json
plugins/plugin-packages/plugin.security-workbench.json
plugins/plugin-sbom/plugin.security-workbench.json
plugins/core-reviewers/plugin.security-workbench.json
plugins/core-output/plugin.security-workbench.json
Workspace discovery is metadata-only and never imports discovered entrypoints. The CLI exposes the validated catalog and effective local registration state through security-workbench plugins list and security-workbench plugins describe <plugin>. Human-readable output bounds, sanitizes, redacts, and defangs plugin-authored metadata; JSON describe output preserves the complete bounded manifest record. Quality labels are required manifest metadata and describe maturity only; they do not imply trust, validity, enablement, policy compliance, or sandboxing. Built-in default and minimal profiles establish the initial registration set. Persisted local configuration is applied next, followed by per-invocation enable/disable overrides; invocation disable wins and invalid plugins remain unavailable.
Registered skills may provide optional summary, about, use_cases, and limits fields. Registered workflows may additionally provide inputs and output. These fields drive compact list output and detail cards; when omitted, the CLI derives bounded fallback text from the registered name, category, and description.
Use discovery metadata for concise catalog guidance only. It does not grant permissions, change profile membership, alter workflow steps, or override runtime policy. Manifest declarations may include matching discovery fields for package catalog consistency, but the statically registered runtime skill or workflow remains authoritative for executable CLI discovery.
Detailed authoring guidance remains in docs/plugins/MAINTENANCE.md and docs/plugins/PLUGIN_DOC_TEMPLATE.md.
Maintenance guidance for adding or changing plugin skills, manifests, docs, fixtures, and smoke coverage lives in docs/plugins/MAINTENANCE.md.
Current first-party plugins remain statically imported by the CLI. The default profile includes every official plugin; the minimal profile includes core-utilities, core-parsers, and core-output.
Persistent local controls:
plugins enable <plugin> persistently enable a known discovered plugin
plugins disable <plugin> persistently disable a known discovered plugin
plugins reset <plugin> remove one persisted override and follow the selected profile
plugins reset --all remove all persisted plugin overrides
The state file is ${XDG_CONFIG_HOME:-~/.config}/security-workbench/config.json. Unknown names are rejected with installation guidance for enable/disable. Reset may clear a stale configured name that is no longer discovered. These commands do not install packages. Resetting the final override removes the state file.
Per-invocation controls:
--profile <profile> choose the initial plugin set
--enable-plugin <plugin> add a valid statically wired official plugin once
--disable-plugin <plugin> remove a plugin once; invocation disable wins on conflict
The effective state controls registration:
enabled plugin: validated imported skills register with the runtime
disabled plugin: skills are not registered
invalid plugin: affected capabilities fail closed with visible diagnostics
missing manifest: affected capabilities fail closed with visible diagnostics
dependent workflow: omitted when any required skill is unavailable
Visibility by command surface:
| Surface | Visibility |
|---|---|
plugins list / plugins describe |
all discovered workspace plugin records, including disabled or invalid records, with effective state and diagnostics |
skills list / skills describe / skills run |
only skills registered from enabled valid plugins |
workflows list / workflows describe / workflows run |
only workflows whose required skills are available in the effective skill registry |
Plugin state output distinguishes profile membership, persisted configuration, invocation overrides, status source, effective state, and validity. These fields explain registration behavior; they do not grant permissions or establish trust.
There is no dynamic plugin loader or external plugin installer. Persisted enable/disable configuration only selects among installed, discovered plugins and never installs or executes unknown code. Enablement is not a trust guarantee and does not grant network, filesystem, persistence, external binary, or exposure permissions. Runtime policy remains responsible for those boundaries.
Current first-party domain boundaries:
plugin-browser-extension
plugin-certificates
plugin-scanner-normalize
plugin-network-registries
plugin-mac-oui
plugin-url-triage
plugin-email
plugin-packages
plugin-sbom
Future first-party/plugin families:
plugin-infrastructure-intel
plugin-cloudformation
plugin-kubernetes
plugin-terraform
plugin-iam-policy
plugin-vulnerability-intake
plugin-ai-agent
plugin-notion
Use the full maintenance checklist in docs/plugins/MAINTENANCE.md. At minimum:
pick owning plugin
keep scope small
declare permissions
update the official plugin manifest skill declaration
declare future exposure intent when relevant
add input/output schema coverage when the skill is stable
add tests, including malformed input
add fixtures if useful
update plugin docs and this inventory
run the relevant package gate before the full gate
Future third-party plugins must also document privacy behavior, network/provider sends, persistence, examples, license compatibility, and validation status before promotion from experimental to beta or stable. A validation GitHub Action may become a future quality signal, but it is not a sandbox or trust guarantee.
define expected input artifact type
list skill steps in execution order
preserve evidence references between steps
state risk and confidence assumptions
add fixture input and golden output coverage
document network behavior and external disclosure
Full gate:
pnpm build
pnpm test
pnpm typecheck:test
./security-workbench-full-smoke.sh