Skip to content

Plugin Development

LizardPope1101 edited this page Jul 29, 2026 · 5 revisions

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

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

Current contract

A manifest declares its identifier, version, description, category, tags, upstream project and license, supported input targets, commands, lifecycle scripts, root requirements, batch capability, 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.
  • 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.

Contract trajectory through v1.0

v0.5 will introduce versioned declarations for accepted and emitted entity types plus structured observations, provenance, and candidate relationships. Later releases add planner compatibility, evidence verification, correlation metadata, and bounded-recursion eligibility. Do not invent or depend on these fields before their schema is merged and documented.

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.

Clone this wiki locally