Security Review Checklist - Docs menu

Security Review Checklist

Plugins can expose external systems to an agent. Review them as a security boundary, not just as helper code.

Manifest Review

  • The manifest URL is stable and served over HTTPS.
  • apiVersion is navigic.plugin/v1.
  • metadata.name is stable and does not change between releases.
  • metadata.version changes when operations, scopes, schemas, risk, auth, or routes change.
  • metadata.publisher is structured and identifies the accountable operator, support email, publisher URL, and verification status.
  • metadata.license is present and uses an SPDX identifier or clear commercial license label.
  • links includes documentation, support, privacy, terms, and changelog URLs served from stable HTTPS locations.
  • release includes version, release timestamp, release notes, breaking changes, migration notes, and optional artifact or manifest digest proof.
  • The live Navigic catalog record marks the plugin lifecycle as available, the release review as approved, and the publisher as verified before setup is enabled.
  • permissions explains each requested provider scope and the operation grants that use it.
  • dataUse discloses processed data categories, model-visible data, storage, provider sharing, and retention.
  • outboundDomains lists every provider domain the plugin calls.
  • observability.redactFields covers authorization headers, access tokens, refresh tokens, signing secrets, credential leases, and provider secrets.

Operation Review

  • Each operation does one narrow job.
  • Read operations are separate from write operations.
  • External-send and destructive operations use approval.defaultMode: "ask" or deny.
  • Write operations use idempotency: "required".
  • Input schemas reject unknown fields with additionalProperties: false when possible.
  • Model hints match the actual behavior. Do not mark a networked or write operation as read-only.
  • Required scopes are the smallest scopes that can complete the operation.

Execute Endpoint Review

  • Host authentication is checked before provider calls.
  • Request JSON is validated before use.
  • Unknown operations fail closed.
  • Expired credential leases fail closed.
  • Idempotency keys are reserved before external writes.
  • Retryable failures release idempotency reservations when a retry should be allowed.
  • Provider responses are normalized into stable success and failure results.
  • Logs contain request IDs and provider request IDs, but not secrets or raw customer credentials.

Provider Webhook Review

  • Signature verification uses the raw request body.
  • Stale timestamps are rejected.
  • Duplicate provider events are deduped with provider-stable fields.
  • Provider events are acknowledged within the provider's documented deadline.
  • User-generated provider content is treated as untrusted input.

Credential Review

  • Long-lived customer credentials are not stored in the plugin repo.
  • Runtime calls use scoped, short-lived credential leases or service tokens.
  • OAuth redirect URIs are explicit and environment-specific.
  • Secret rotation has an operational path.
  • Local development secrets stay outside committed source files.
  • Public support guidance tells users not to paste provider access tokens, refresh tokens, client secrets, signing secrets, or verification tokens into chats or tickets.

Test Review

Add tests for:

  • valid manifest shape;
  • missing or invalid host authentication;
  • unknown operation IDs;
  • invalid operation input;
  • expired credential leases;
  • missing write idempotency keys;
  • duplicate idempotency keys;
  • provider rate limits and retryable failures;
  • log redaction;
  • provider webhook signature failure;
  • provider webhook replay or stale timestamp rejection.