Community Pen-Test Handbook
What this page is
Stigmem is an open federated protocol. External security scrutiny makes it stronger. This handbook covers everything you need to run a structured engagement — from scoping your test to getting your findings in front of the maintainers.
For the project's vulnerability disclosure policy and supported-version
matrix, see SECURITY.md.
For the technical threat model, see spec/security/threat-model.md.
1 · In-scope targets
The following surfaces are explicitly in scope for community pen testing.
/v1/facts, /v1/query, /v1/recall, /v1/cards/*, /v1/graph/*, /v1/synthesis, /v1/decay, /v1/conflicts, /v1/subscriptions, /v1/federation/*, /v1/admin/*. Authenticated and unauthenticated paths; read and write surfaces.assert_fact, query_facts, recall, lint_scope tool surface./v1/admin/audit-log; log tamper-resistance.Priority finding categories
The following finding classes are of the highest interest to maintainers.
Authentication bypass
Accessing write endpoints without a valid API key, or escalating a public-scoped key to read/write team or local facts.
Cross-org data leakage
A capability token or API key granting access to facts beyond its declared scope.
Federation peer impersonation
Successfully acting as a peer node without a valid mTLS certificate and matching org manifest.
Capability token replay or forgery
Replaying a revoked token, forging a signature, or bypassing the nonce/timestamp window.
Prompt injection via recall
Bypassing the recall-time content sanitizer (ADR-003 defense-in-depth) to inject instructions into an LLM context via stored fact values.
Quarantine garden bypass
Causing an untrusted fact to enter the main fact store without passing through quarantine review.
Source Attestation bypass
Writing facts without a valid attestation in enforce mode.
2 · Out-of-scope targets
Testing these will not result in credit and may violate third-party terms of service.
fact_write quota dimension (pre-reset hardening) to test post-hardening.3 · Safe-harbor terms
If you conduct good-faith testing within the scope above, Eidetic
Labs will not pursue legal action and will publicly credit you in
SECURITY.md and the relevant release notes (unless you prefer
anonymity).
"Good faith" means
- You do not access, exfiltrate, or modify data that is not yours.
- You test against your own node instance or a dedicated test environment — not a third-party node without explicit written permission from that operator.
- You report findings privately before public disclosure (see §8 Disclosure timeline).
- You do not cause service disruption to other operators or their users.
- You do not exploit a finding beyond what is necessary to confirm it exists.
- You do not automate requests at a rate that would degrade a shared test environment.
Violating any of the above conditions voids the safe-harbor commitment for that engagement.
4 · Setting up a test environment
The fastest way to get a disposable Stigmem node for testing:
# Clone the repo
git clone https://github.com/eidetic-labs/stigmem
cd stigmem
# Start a node with Docker Compose (SQLite backend, no federation)
docker compose up -d stigmem-node
# Create a test API key (save the returned plaintext key — it is shown once only)
curl -X POST http://localhost:8000/v1/admin/keys \
-H "Authorization: Bearer $STIGMEM_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"label": "pentest", "scopes": ["public", "team"]}'
For federation testing, a 2-node topology is available:
docker compose -f docker-compose.federation.yml up -d
For a 4-node federation soak including backpressure and scope-propagation invariants, see the Federation: 4-Node Soak guide.
Recommended test matrix
5 · Reproducer expectations
Every finding submitted via GitHub private advisory should include a self-contained reproducer. Findings without a working reproducer will be triaged as "needs more info" and may not receive credit until one is provided.
Environment
Stigmem version/commit, backend type (SQLite/libSQL/Postgres), OS.
Setup steps
Exact commands to provision a test node and any required keys or data.
Attack steps
The exact request sequence, including all HTTP headers and bodies, in order.
Expected behavior
What should happen if the control is working correctly.
Observed behavior
What actually happened (HTTP response, data returned, side effect).
Impact assessment
What an attacker gains; whose data; what privilege level; can it pivot.
Example reproducer for a hypothetical scope bypass:
Environment: stigmem the pre-reset v1.0-rc snapshot, SQLite backend, Docker Compose
Commit: abc1234
Setup:
docker compose up -d stigmem-node
ADMIN_KEY=$(docker compose exec stigmem-node cat /run/secrets/admin_key)
curl -X POST http://localhost:8000/v1/admin/keys \
-H "Authorization: Bearer $ADMIN_KEY" \
-d '{"label":"victim", "scopes":["team"]}' # returns: VICTIM_KEY=stgm_...
curl -X POST http://localhost:8000/v1/admin/keys \
-H "Authorization: Bearer $ADMIN_KEY" \
-d '{"label":"attacker", "scopes":["public"]}' # returns: ATTACKER_KEY=stgm_...
curl -X POST http://localhost:8000/v1/facts \
-H "Authorization: Bearer $VICTIM_KEY" \
-d '{"entity":"stigmem://victim/secret","relation":"value","value":"secret123","scope":"team"}'
Attack:
curl -X POST http://localhost:8000/v1/recall \
-H "Authorization: Bearer $ATTACKER_KEY" \
-d '{"query":"secret","scopes":["public","team"]}'
Expected: Only public-scoped facts returned; team-scoped facts excluded.
Observed: team-scoped fact "secret123" returned in response.
Impact: Any public-scoped API key can read all team-scoped facts. Full data exfiltration of team scope.
6 · Report template
Use this template when opening a GitHub Security Advisory:
## Summary
[One-sentence description of the vulnerability class and impact.]
## Vulnerability class
[OWASP / STRIDE category, e.g., "Broken Object-Level Authorization (BOLA)", "Authentication bypass"]
## CVSS v3.1 score and vector
Score: X.X
Vector: CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:N
## Affected versions
[e.g., the pre-reset v1.0-rc snapshot, all versions up to commit abc1234]
## Environment
- Stigmem version/commit:
- Backend type:
- OS:
## Reproducer
[Self-contained steps per §5 above]
## Expected behavior
## Observed behavior
## Impact
[What can an attacker do? Whose data is at risk? What privilege level is achieved?]
## Suggested fix (optional)
[Concrete code-level or protocol-level fix if you have one]
## Disclosure preference
[ ] Credit me publicly as: [name/handle]
[ ] I prefer anonymous credit
[ ] I do not need credit
7 · Severity guidance
Use CVSS v3.1 as the primary severity signal. For Stigmem-specific surfaces:
local or team facts without authorization; capability token forgery.local facts via a public query path); replay-attack success against the federation handshake; Source Attestation bypass in enforce mode.8 · Disclosure timeline
The Stigmem project follows coordinated disclosure with a default window of 90 days from acknowledgment of a valid finding.
Exceptions to the 90-day window:
Actively exploited in the wild
We coordinate with you and may disclose sooner, potentially within 7 days.
Straightforward fix available
We target faster publication and will communicate the updated timeline.
90 days is insufficient
If a patch requires architectural changes that take longer, we will discuss an extension with you. We will not request an extension more than once without a concrete timeline.
We keep reporters informed of patch progress and release dates throughout the window. If you have not heard from us within 7 days of filing, ping the advisory thread directly.
9 · Coordinating a structured engagement
If you want to run a structured pen test (vs. individual ad-hoc finding reports), open a GitHub Discussion with:
Intended scope
Which API surfaces, which spec version, which trust boundary.
Test environment setup
Your own node, isolated network, etc.
Proposed timeline
Active-hardening context
Anything you'd like to know about (e.g., "we're hardening TB-2 in pre-reset hardening — here's what's already in flight").
Maintainers will confirm scope, share any active-hardening context, and coordinate acknowledgment and credit at the end of your engagement.
10 · Known hardening gaps
The following are known gaps planned for the pre-reset hardening work (carried forward to v0.9.0a1). You are welcome to test and report them — findings in this list will be triaged as known rather than novel, but novel attack paths against them are still valuable findings and eligible for full credit.
The full threat model with STRIDE analysis per trust boundary lives
at spec/security/threat-model.md.
11 · Recognition
Stigmem does not currently operate a paid bug bounty program. Valid findings are recognized with:
Hall of fame
Your name or handle is added to the SECURITY.md acknowledgments section and the fixing release's changelog.
Attribution in the spec errata
If your finding affects wire-format or protocol behavior, you are credited in the relevant modular spec changelog as a contributor to that revision.
Coordinated disclosure credit
The GitHub Security Advisory, when published, lists you as the reporter.
If you prefer to remain anonymous, say so in your report template
([ ] I prefer anonymous credit) and we will honor that throughout
all public communications.
This recognition model may evolve as the project scales.