Security Workbench is intended to be community-driven while remaining secure by default. Contributors should be able to add skills, parsers, reviewers, pipelines, exporters, docs, and fixtures without changing the core runtime unnecessarily.
The project values:
correctness
security
simplicity
maintainability
observability
practical usefulness
You can contribute:
skills
parsers
reviewers
pipelines
plugins
enrichment connectors
scoring models
export templates
UI panels
test fixtures
schemas
documentation
examples
security reviews
bug reports
research methodology
A suspicious signal is not proof. Inference must be labeled as inference.
Findings should reference evidence records. Parsers should preserve observations.
No hidden network calls. No hidden persistence.
Prefer small functions, typed inputs/outputs, fixtures, and clear failure cases.
Avoid magic config loading, hidden fallbacks, silent failures, or undeclared side effects.
Analysis behavior belongs in plugins. The runtime owns registration, execution, policy, redaction, and shared result handling.
A skill contribution should include:
skill metadata
permission declaration
implementation
unit tests
malformed input tests
fixtures or examples when useful
README/docs update
Future skills may also require:
input schema
output schema
golden output tests
exposure metadata
Required behavior:
return structured data
do not print from skill logic
do not make undeclared network calls
do not persist artifacts directly
do not execute untrusted artifact content
fail clearly on malformed input
Recommended directory:
plugins/<plugin-name>/src/<skill-name>.ts
Parser skills should:
treat input as hostile
use reviewed parser dependencies only
apply bounded parsing behavior
return observations and warnings
avoid risk scoring
avoid findings
avoid network lookups
avoid filesystem access from artifact content
include malformed fixtures/tests
Risk review belongs in reviewer/scoring plugins, not parser primitives.
Pipeline support is not implemented yet.
When implemented, a pipeline contribution should include:
pipeline definition
description
input type/schema
output type/schema
example input
example output
golden output test
policy behavior test
Pipelines should compose registered skills rather than hardcoding analysis behavior in adapters.
External enrichment is not implemented yet.
A future enrichment connector must include:
source name
source documentation
network permission declaration
data sent externally
timeout behavior
rate-limit behavior
cache behavior
failure behavior
tests with mocked responses
External lookups must be disabled by default unless runtime policy enables them.
Security Workbench uses two related concepts.
Top-level fixtures live under:
fixtures/
Use these for:
manual CLI examples
demos
smoke tests
docs examples
shared fake artifact samples
Fixture policy and inventory live in:
docs/FIXTURES.md
fixtures/README.md
Package-local testdata may be used for golden tests or internal test cases:
plugins/<plugin>/testdata/
packages/<package>/testdata/
Golden output changes should be intentional and reviewed.
General rules:
small focused functions
typed inputs and outputs
minimal dependencies
clear errors
no silent failures
I/O separated from business logic
no hardcoded paths except test-local paths
Comments should explain why, not merely what.
Public modules, public functions, and plugin contracts should be documented.
Expected tests, as applicable:
schema tests
unit tests
fixture tests
golden output tests
malformed input tests
network-disabled tests for enrichment skills
redaction tests for sensitive artifacts
policy behavior tests
exposure policy tests for hosted/API/MCP surfaces
Baseline commands:
pnpm build
pnpm test
pnpm typecheck:test
./security-workbench-full-smoke.shFor isolated smoke validation, list and run explicit sections:
./security-workbench-full-smoke.sh --list-sections
./security-workbench-full-smoke.sh --section plugin:network-registriesPackage-specific examples:
pnpm --filter @security-workbench/core-utilities test
pnpm --filter @security-workbench/core-parsers test
pnpm --filter @security-workbench/cli testBefore merging, check:
Does this make hidden network calls?
Does this log secrets?
Does this persist raw inputs?
Does this execute untrusted artifact content?
Does this overstate confidence?
Does every signal/finding have evidence?
Does it handle malformed input cleanly?
Does it fail closed when policy blocks execution?
Does it add unnecessary dependencies?
Does docs/smoke coverage need updating?
Valid plugin quality labels are:
stable
beta
experimental
deprecated
Quality labels describe maturity and support posture only. core is a package role, not a quality label. unreviewed and third_party are trust-tier values, not quality labels.
New community plugins normally start with the experimental quality label and an appropriate non-official trust tier until review establishes otherwise.
Promotion requires:
docs
tests
fixtures
security review
clear ownership
stable schemas
Documentation should stay small and engineering-focused. Prefer updating the canonical document instead of adding a new topic-specific file.
Core docs:
README.md project front door
docs/ENGINEERING.md runtime, repo layout, implementation rules
docs/ROADMAP.md current status, backlog, and next work
docs/SECURITY_MODEL.md threats, privacy, exposure, output safety, release gates
docs/FIXTURES.md fixture policy and inventory
docs/plugins/README.md plugin and skill inventory
docs/plugins/<plugin>.md per-plugin behavior and limits
fixtures/README.md short fixture-folder pointer
Every plugin should document:
what it does
what inputs it accepts
what outputs it returns
whether it uses network
what data it sends externally
example runs
known limitations
Every public pipeline should eventually document:
workflow purpose
input artifact type
steps
network behavior
expected outputs
example finding
Avoid duplicating full skill inventories outside plugin docs.
Security Workbench documentation is intentionally consolidated. Not every PR should update every document.
| Document | Update cadence | Purpose |
|---|---|---|
README.md |
When install, quickstart, or headline status changes | Project front door |
docs/ENGINEERING.md |
When runtime, adapter, policy, or repo-layout behavior changes | Stable engineering handoff |
docs/ROADMAP.md |
When milestones, next work, completed work, or deferred work changes | Canonical implementation status |
docs/SECURITY_MODEL.md |
When trust boundaries, privacy, exposure, output safety, or release gates change | Stable security model |
docs/FIXTURES.md |
When top-level fixtures are added, removed, or renamed | Fixture policy and inventory |
docs/plugins/README.md |
When plugin packages or skill counts change | Plugin index and inventory overview |
docs/plugins/<plugin>.md |
When that plugin gains, removes, or materially changes skills | Per-plugin behavior and examples |
Use two fixture locations deliberately:
fixtures/ fake demo/manual/smoke inputs safe to commit and share
testdata/ package-specific golden/unit test inputs and expected outputs
| Fact | Canonical home |
|---|---|
| Repo layout, runtime flow, CLI behavior | docs/ENGINEERING.md |
| Plugin package index and skill inventory | docs/plugins/README.md |
| Per-plugin behavior and examples | docs/plugins/<plugin>.md |
| Current roadmap and backlog | docs/ROADMAP.md |
| Security, privacy, exposure, and output-safety rules | docs/SECURITY_MODEL.md |
| Fixture policy and inventory | docs/FIXTURES.md |
Plugin-only changes usually update the owning plugin doc, docs/plugins/README.md, fixtures, and the roadmap.
Before opening a PR:
[ ] Code is small and focused.
[ ] Runtime boundaries are preserved.
[ ] Permissions are declared.
[ ] Exposure metadata is added where needed.
[ ] Tests are added or updated.
[ ] Fixtures are added or updated where useful.
[ ] Golden outputs are updated intentionally.
[ ] Network behavior is declared.
[ ] Redaction behavior is considered.
[ ] Documentation is updated.
[ ] Smoke coverage is updated if behavior changed.
[ ] No hidden persistence is introduced.
[ ] No unnecessary dependencies are added.
Recommended labels:
bug
skill
parser
reviewer
pipeline
plugin
enrichment
scoring
exporter
ui
api
cli
mcp
privacy
security
docs
good-first-issue
needs-design
Review should prioritize:
correctness
security
local-first behavior
evidence quality
testability
maintainability
clarity
Performance matters, but not at the expense of correctness or safety.