docs: add VotingPlugin security threat model

[BenCodez]

Summary

• add a repository-specific security threat model for Codex/security review
• document vote authenticity, reliable delivery, transport authentication, Control, authorization, storage, lifecycle, and resource-exhaustion boundaries
• add high-value crash/reload/mixed-version attack stories and security severity calibration
• explicitly distinguish documented compatibility/trusted-operator behavior from actual trust-boundary failures
• point AGENTS.md security work at the threat model

Notes

Documentation only; no runtime behavior changes.

The model is intentionally aligned to current master, including shared transport authentication, reliable vote delivery, and VotingPlugin Control so scans focus on bypasses/cross-feature failures rather than stale pre-hardening assumptions.

Summary by CodeRabbit

• Documentation
  • Added a security threat model covering key trust boundaries, attacker-controlled inputs, and areas of the plugin to consider during security reviews.
  • Added guidance for assessing potential findings, including how to distinguish security issues from documented compatibility behavior and trusted administrator configuration.
  • Security review guidance now directs reviewers to consult the threat model and verify conclusions against the current code and tests.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-28T23:30:23.970502Z	a4cc0e7	New commits
🔒 Security Review	✅ Completed 2026-09-28T22:47:43.428121Z	621c90f	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Warning

Review limit reached

Next included review available in 15 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: b7e0acf2-a3d2-49c6-b550-649783580d97

📥 Commits

Reviewing files that changed from the base of the PR and between 621c90f and a4cc0e7.

📒 Files selected for processing (1)

• docs/security-threat-model.md

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 08843d00-3773-4e65-88a5-e65881480798

📥 Commits

Reviewing files that changed from the base of the PR and between b6d2aea and 621c90f.

📒 Files selected for processing (2)

• AGENTS.md
• docs/security-threat-model.md

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

📜 Recent review details

⏰ Context from checks skipped due to timeout. (3)

• GitHub Check: build
• GitHub Check: Analyze (java-kotlin)
• GitHub Check: Analyze (actions)

🧰 Additional context used

🪛 LanguageTool

docs/security-threat-model.md

[style] ~247-~247: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...iscord, webhook, or broadcast sink. 13. A very large but schema-valid authenticated envelope...

(EN_WEAK_ADJECTIVE)

🔇 Additional comments (2)

docs/security-threat-model.md (1)

1-261: LGTM!

AGENTS.md (1)

7-10: LGTM!

---

📝 Walkthrough

Walkthrough

The pull request adds a repository-specific security threat model and instructs reviewers to consult it when reviewing security-sensitive changes and triaging vulnerabilities.

Changes

Security review guidance

Layer / File(s)	Summary
Threat model scope and review instruction AGENTS.md, docs/security-threat-model.md	The threat model defines security objectives, attacker inputs, and trust assumptions. AGENTS.md directs reviewers to consult the model and verify conclusions against current code and tests.
Transport, routing, and Control review criteria docs/security-threat-model.md	The model lists review criteria for transport authentication and delivery, presence-based routing, VotingPlugin Control, enrollment, credentials, and plugin deployment.
Execution, resource, storage, and runtime checks docs/security-threat-model.md	The model covers interpreter crossings, player authorization and transactional state, resource and storage bounds, and reload or runtime-replacement behavior.
Compatibility, attack stories, and severity criteria docs/security-threat-model.md	The model defines compatibility and scan-calibration rules, lists attack stories and previously reviewed areas, and specifies severity criteria and report requirements.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 621c9

This documentation change preserves the documented compatibility and Control-operation boundaries. No actionable merge-blocking risk is established.

Architecture Summary

Architecture risk: 🔵 Low · up to 621c9

The change affects 2 systems.

Changed systems: AGENTS.md, docs

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — AGENTS.md (service) was modified; 1 changed file maps to changed impact.
• observed — docs (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in AGENTS.md: Adds security-review guidance requiring consultation of the repository threat model and verification against code and tests; it limits security findings to cases that cross the documented attacker or trust boundary.
• observed — Modified behavior in docs/security-threat-model.md: Adds the threat model’s scope, security objectives, attacker-influenced inputs, and trust assumptions, including the distinction between unrestricted filesystem/plugin administrators and lower-privileged actors.
• observed — Modified behavior in docs/security-threat-model.md: Defines review criteria for shared-transport authentication and compatibility modes, reliable reward-bearing delivery and deduplication, and presence-based routing. It identifies authentication bypasses, replay and lifecycle failures, and stale or inconsistent routing state as cases to examine.
• observed — Modified behavior in docs/security-threat-model.md: Adds VotingPlugin Control review surfaces and checks for configuration/YAML access, secret handling, revisions, recovery, enrollment and credentials, and privileged plugin deployment. Deployment checks include actor/attempt binding, artifact verification, path and activation races, and recovery behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a VotingPlugin security threat model and related documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 621c90f7f1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[BenCodez]

Review feedback addressed.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6f23c992fa

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 51e40354c0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 37ec4014ed

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".