ktg-plugin-marketplace/plugins/llm-security/CONTRIBUTING.md

Contributing

Thanks for the interest. This document is the honest answer to "how do I contribute?" — and the answer is mostly fork and own. Read on.

---

TL;DR

You want to …	Do this
Report a bug	Open an issue on Forgejo
Ask a question	Open an issue on Forgejo
Suggest a small fix	Open an issue with the diff inline; the maintainer may apply it
Propose a new scanner / hook / command	Open an issue first; expect "fork & own" for anything beyond stabilization
Build enterprise features (dashboards, fleet policy, runtime firewall, IDE LSP, compliance pack, ticketing connectors)	Fork the repo. Build it. Ship it under your own name. This is encouraged.
Report a security vulnerability	See SECURITY.md — do not open a public issue

---

Why this project does not accept pull requests

This is a solo open-source project, MIT-licensed, maintained alongside a day job by one person. Accepting PRs sounds nice but in practice creates problems the maintainer cannot solve sustainably:

• Review cost. Every PR needs careful security review (this is a security plugin — a malicious PR is the literal threat model). Solo capacity does not scale to that.
• Maintenance burden. Merged code becomes the maintainer's responsibility forever. Every contributed scanner is one more thing to test, port across Claude Code versions, and keep current.
• Direction control. The project has a deliberate scope (see README "Project scope"). PRs that expand scope force a "no, sorry" that is worse for the contributor than "fork it and ship your version."

The MIT license already gives you everything you need to take the code in any direction. Use it.

---

Issues are welcome

Open issues for:

• Bugs — reproducer, expected vs actual behavior, plugin version (cat .claude-plugin/plugin.json), Claude Code version, OS
• False positives — minimal example that triggers a finding that shouldn't fire, plus the .llm-security-ignore rule you ended up using (or "no clean way to suppress" — that's useful signal)
• False negatives — known attack pattern that should trigger a finding but doesn't. Cite the OWASP / research source if you have one.
• Documentation gaps — places where the README, hardening guide, or threat model is wrong, stale, or missing
• Compatibility regressions — Claude Code version X stopped working

This plugin lives in the ktg-plugin-marketplace monorepo. Issues are tracked there, scoped to the llm-security plugin:

https://git.fromaitochitta.com/open/ktg-plugin-marketplace/issues

Tag the issue with the plugin name in the title — e.g. [llm-security] entropy scanner false positive on GLSL shader.

The maintainer reads them. Response is best-effort, not real-time.

---

Forking — the recommended path

If you have feature ideas larger than a paragraph, fork the repo. The MIT license permits it, this contributing guide encourages it, and the project is intentionally architected so a fork can diverge cleanly.

What forking gives you

• Full ownership of direction, release cadence, and roadmap
• Freedom to add enterprise features that this project will never accept (web dashboard, fleet policy server, runtime firewall, IDE LSP scanner, compliance PDF generator, Jira/ServiceNow/Slack/PagerDuty integrations, multi-tenancy, ML-based detectors, marketplace UI, central audit storage, SSO/SCIM, RBAC)
• Ability to charge for it. MIT does not require attribution beyond preserving the LICENSE file in source distributions.

How to fork well

1. Clone, don't subtree. Copy plugins/llm-security/ into a fresh repo. Keep the LICENSE file. Keep the SECURITY.md (or replace with your own — but change the contact address).
2. Rename the plugin. Update .claude-plugin/plugin.json name, description, and repository. Update the bin entry in package.json if you publish to npm. Do not ship a plugin called llm-security from a fork — it confuses users and breaks issue triage upstream.
3. Decide your knowledge-base policy. The knowledge/ directory cites OWASP, DeepMind, Pillar, ToxicSkills, and other published research. Citations belong to the original sources, not to this project. Keep them.
4. Run the self-scan. node scanners/scan-orchestrator.mjs . should produce 0 findings on a healthy fork — the .llm-security-ignore rules are documented and reasoned. If your fork triggers new findings, resolve them or document the suppression.
5. Re-establish trust. A fork is a new project. Document who you are, what your release cadence is, what your security disclosure process is (don't reuse security@fromaitochitta.com — that mailbox routes to the original maintainer).
6. Track upstream loosely. When a security fix lands here, port it. When a feature lands here, decide if it fits your direction. Diverge on purpose.

What not to do when forking

• Do not rebrand and silently republish under the same name. It breaks downstream trust.
• Do not strip the LICENSE. MIT requires you preserve it.
• Do not represent your fork as the upstream project. "Fork of llm-security by Kjell Tore Guttormsen, maintained by [you]" is the honest framing.

---

Small fixes the maintainer may apply

For tiny corrections — a typo, a broken link, a clearly wrong regex, a missing entry in a blocklist — open an issue with the proposed change inline. The maintainer may apply it directly. Credit goes in the commit message.

This is not a back-door for PRs. It is a pragmatic shortcut for changes that take less time to apply than to review.

---

Development setup (for forkers)

git clone <your-fork-url>
cd <your-fork>
npm install        # zero runtime deps; this only installs node:test for testing
npm test           # 1777+ tests at v7.3.0
npm run lint       # if your fork adds a linter

Tests live in tests/. The shape is tests/<area>/<file>.test.mjs using Node's built-in node:test. No Jest, no Vitest, no Mocha. The dependency budget is intentionally zero for hooks and scanners.

For details on architecture, see CLAUDE.md — that file is the authoritative architecture overview.

---

Code of conduct

Be respectful. The maintainer reserves the right to close issues that are abusive, off-topic, or in bad faith. There is no separate Code of Conduct document because there is no community process to govern; this is a solo project with an issue tracker.

---

License

MIT. All contributions submitted via issues — including inline-diff suggestions — are accepted under the same license.