Plugin Development

Plugin Development

Tool-specific behavior belongs in a self-contained plugin, not in framework core. Plugins are source-independent adapters inside a governed, versioned contract.

Layout

plugins/<tool>/
├── manifest.json
├── install.sh
├── update.sh
├── remove.sh
├── doctor.sh
└── normalize.py

Start from docs/plugin-template and follow the canonical Plugin API.

Current contract

A schema-2 manifest declares its identifier, version, description, category, tags, upstream project and license, supported input targets, explicit accepted and emitted entity types, commands, lifecycle scripts, root requirements, batch capability, a plugin-owned normalizer, and argument-array adapters.

• The plugin ID must match its directory.
• Lifecycle paths cannot escape the plugin directory.
• Adapter commands must be arrays; never interpolate targets into shell text.
• Every batch-supported target type requires an adapter.
• Every batch plugin must declare a regular, non-symlink normalize.py contained within its plugin directory.
• Invalid or unsupported contracts are rejected during catalog loading.
• Lifecycle scripts require correct executable modes and SPDX identifiers.

Core target vocabulary now includes address, domain, email, file, image, ip, name, phone, and username. A plugin supports only the types it explicitly declares.

Normalizer contract

Core runs the normalizer against a completed job's preserved raw-output directory. The normalizer must be deterministic, standard-library-only, network-free, read-only, and consistently sorted. It emits one schema-versioned JSON object containing normalized findings, deterministic candidate entities when declared, and exact source-file references. Missing, malformed, oversized, unsafe, or out-of-bound output must fail visibly rather than being treated as an empty successful result.

Normalizer changes require synthetic positive, negative, malformed, and missing-output fixtures. See the canonical Plugin API and Reporting.

Contract trajectory through v1.0

v0.5 delivers schema-2 entities.accepted and entities.emitted declarations plus deterministic candidate observations with exact provenance. All shipped plugins use the schema-2 contract. Later releases add planner compatibility, evidence verification, relationship and correlation metadata, and bounded-recursion eligibility through separately versioned contracts.

Future adapters must:

• keep source assertions separate from analyst findings and framework inferences;
• preserve raw output and exact provenance for every normalized value;
• emit deterministic, versioned structures;
• avoid global identity assumptions or hidden confidence calculations;
• declare network, authentication, rate-limit, and scope behavior; and
• remain safe when an emitted entity is not eligible for further pursuit.

Lifecycle and validation

Install, update, remove, and doctor operations must be idempotent where practical, support safe dry-runs, and avoid deleting user data or unrelated dependencies.

osint forge validate
osint forge validate --json
./scripts/dev-check.sh

Add deterministic contract and lifecycle tests. Exercise installation and authorized runtime behavior in a disposable current Debian VM before release acceptance.

Governance review

Document upstream maintenance, authoritative source, license compatibility, supported platforms, credentials or API keys, network behavior, safe defaults, authorization requirements, emitted data, and the accept/defer/reject decision. Update THIRD_PARTY_NOTICES.md for accepted plugins. Never submit credentials, case data, real targets, or source the project cannot legally redistribute.