# 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`](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) ```bash git clone cd 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//.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`](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](LICENSE). All contributions submitted via issues — including inline-diff suggestions — are accepted under the same license.