Publishing guide
Current submission availability, plugin requirements, and publishing qualification
MacCrab Rave distributes signed forensic plugins. The catalog release for MacCrab 1.22.3 contains 19 first-party collectors; see release scope and qualification limits. Community publishing and update workflows are still being qualified.
Submission availability
Check the submission page for the deployed intake setting before signing in. Intake can be closed, restricted to invited accounts, or open. An open setting permits submissions; it does not mean every publishing or runtime qualification gate has passed. If availability cannot be checked, the page should say so.
| Channel | Purpose | Current qualification |
|---|---|---|
official | MacCrab first-party collectors | 18 additions require MacCrab 1.22.3; Posture Pro 0.3.1 retains its existing requirements. See host qualification and known limitations. |
contrib | Independent publishers | No published community plugins. Complete submission, revision, CI recovery, review, and update publication still need end-to-end qualification. |
Signing and reviewed publication are separate from submitting a form. There is no promised turnaround or automatic promotion to a different execution privilege level.
Execution and capabilities
First-party plugins run in a Developer-ID-validated, unsandboxed process with the host’s privileges, including Full Disk Access when granted to MacCrab. Posture Pro declares read-only metadata collection and no outbound network use. Its first-party execution path does not enforce those filesystem/network restrictions.
Community plugins use a different execution path. Do not infer its restrictions or privilege equivalence from the first-party example, a catalog badge, or a manifest alone. Qualification must exercise the actual installed host and archive before containment claims are published.
A manifest records requested reads, network connections, subprocess paths, and other capabilities. Declare each access, its purpose, and the effects of denied permissions. Schema validation checks the declaration’s shape; it does not prove runtime enforcement or that every behavior was declared. Identity signatures likewise do not prove safe behavior or complete collection.
Prepare a collector
A collector reads a defined source and emits structured records over the host’s supported NDJSON protocol. Prepare:
- A
manifest.jsonand executable with matching plugin ID/version, plus a detached Ed25519 signature and publisher public key. - Exact source revision and build/toolchain instructions. For an independent reproducibility claim, another builder must reproduce the canonical hash from those sources.
- Precise data-source and output descriptions, privacy classification, required permissions, resource limits, and behavior when collection is unavailable or incomplete.
- The actual release archive and its digest, with test evidence for each claimed app/OS/architecture combination. MacCrab’s Intel support does not make an arm64-only plugin compatible with Intel.
- An author identity and security contact for review and maintenance.
The current Posture Pro source is useful for understanding the wire format, but its published grade/coverage and acquisition limitations must not be copied as qualification standards.
Local checks
From a checked-out Rave repository, validate a manifest against the local schema:
python3 - <<'PY'
import json
from pathlib import Path
from jsonschema import Draft202012Validator
schema = json.loads(Path("schemas/manifest.json").read_text())
manifest = json.loads(Path("path/to/plugin/manifest.json").read_text())
Draft202012Validator(schema).validate(manifest)
print("Manifest schema: OK")
PY
Replace the example manifest path with your own. Run the package’s meaningful tests and build twice using the declared toolchain. Compare both packaged archives with tools/maccrab-rave-canonical-hash; matching your own builds is only the first reproducibility check. Independent rebuilding must also match the proposed released archive.
Validate installation and collection on a controlled test Mac using the intended execution path, including denied access and changing source data. Record incomplete results explicitly. See verification for signature and digest inspection. Passing local tests does not certify the publishing workflow or supported host matrix.
Publishing requirements
The required lifecycle is:
- Submit the exact source revision, version, capabilities, and release identity through the available intake path.
- Run schema, signature/publisher-pin, reproducibility, capability-review, and host-qualification checks against that revision.
- Receive actionable review feedback and submit a new revision if needed. Changed bytes need renewed checks and approval.
- Approve the checked entry and archive, sign through the publication procedure, and verify the bytes actually served.
- Exercise the same process for updates, with access changes visible to operators and previous version history retained.
The submission implementation includes revision and retry controls, CI feedback, and owner approval bound to the exact reviewed entry. The complete production journey remains unqualified. Do not rely on automatic release discovery or publication until that journey has passed.
Prove publisher key ownership
When intake permits your account, the form asks you to download an expiring challenge and sign it locally with the publisher key for your archive. The challenge binds your current sign-in, repository, plugin, version, release tag and public key. Changing those fields requires a new challenge; each challenge can be used only once.
Use the tools/sign-publisher-challenge helper from the public submissions repository with an Ed25519 PEM private-key file:
python3 tools/sign-publisher-challenge --challenge publisher-challenge.txt --key /path/to/publisher-key.pem
Paste only the printed signature into the form. Never upload the private key or paste it into the site. A key-possession proof identifies the signing key; it does not establish that the plugin is safe or approved. Revisions need a fresh proof, while a retry of deferred PR creation uses the proof already recorded for that submission.
Analyzers and kits
Analyzer source packages exist, but external analyzer execution is not supported by the published host. The planned analyzer contract will accept selected case evidence, explain missing inputs, and link findings to supporting artifact IDs. Providing selected inputs does not itself sandbox an unsandboxed executable.
No kits are published and kit expansion is not implemented. Additional analyzers and bundles require the supporting host release and their own qualification.
Namespace and review
com.maccrab.* is reserved for MacCrab first-party plugins and rejected for community submissions. Confusingly similar vendor names can receive a needs_namespace_review flag requiring owner review. The flag is not an endorsement or automatic rejection; use a clearly distinct vendor namespace and provide context to the owner when needed.
Undeclared access, unsupported compatibility claims, missing privacy handling, and irreproducible claimed builds must be resolved before publication. A declared network endpoint or subprocess is a review request, not blanket permission or a guarantee the host will permit it.
Submission budgets and rate limits apply; there is no unlimited-resubmission guarantee. Contact maccrab@peterhanily.com for review questions.