Extension API
The community extension contract: a manifest that declares every permission it needs, a curated registry, fixture proof, and the COMMUNITY to INCUBATING to OFFICIAL lifecycle.
What can be extended
SecHelix accepts community-built adapters, catalog packs, eval packs, policy packs, reporters, specialists, and integrations. The registry is curated: a pull request can propose an extension, but it cannot make itself official.
python scripts/validate_extensions.pyThe lifecycle
- ProposeOpen the extension proposal issue before implementation.
- SubmitFork the repository and add extensions/community/<extension-id>/extension.json plus the implementation, documentation, and synthetic fixtures.
- Contract checksCI validates the manifest, declared permissions, safe defaults, repository paths, registry identity, and the test command.
- Safety reviewMaintainers review data handling, dependencies, network, filesystem, subprocess, secret access, and evidence provenance.
- Fixture proofThe extension passes a vulnerable and clean, or positive and negative, fixture pair where the type permits it.
- Channel decisionAccepted submissions begin as COMMUNITY. Maintainers may later promote proven work to INCUBATING or OFFICIAL in a separate reviewed change.
| Channel | Meaning |
|---|---|
| COMMUNITY | Accepted into the curated registry. A reviewable identity, not an endorsement. |
| INCUBATING | Promoted after demonstrated use, in a separate maintainer review record. |
| OFFICIAL | Maintained under the SecHelix release process. |
The manifest
schemas/extension-manifest-v1.schema.json requires the schema version, an ID, a name, a version, a summary, the extension type, the lifecycle, compatibility, entrypoints, and capabilities. Permissions, safety, author, and repository fields complete the declaration.
- The manifest must declare all authority it needs. Undeclared network, filesystem, subprocess, or secret access is grounds for rejection.
- Community extensions must default to static, local-safe, or staging-safe operation.
- Destructive actions and production mutation are forbidden by the v1 manifest contract.
- Registration does not execute or install code automatically. It creates a reviewable identity and lifecycle record.
Start from examples/extension-manifest.example.json, replace every example value, and add the matching entry to extensions/registry.json with lifecycle COMMUNITY.
Review evidence
A reviewable submission includes:
- A concise threat and trust-boundary note.
- Complete permission and data-handling declarations.
- Synthetic fixtures with deterministic expected output.
- A dependency and licence inventory.
- Redacted logs or evidence artifacts from the test command.
- Limitations and known false-positive traps.
- Documentation that distinguishes scanner signals from verified findings.
python -m unittest discover -s tests -p "test_*.py" -vThe extension boundary
Organizations that need company-specific roles, forbidden deployment states, required scanners, severity overrides for regulated assets, or custom report schemas should use a private policy pack rather than an extension. That path changes the decision without changing the open core.