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`](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 <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`](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.