62a9335772
No behavior changes. Sets the public stance, tightens documentation, and removes coherence drift so anyone forking or downloading the plugin gets a consistent starting point. Added: - CONTRIBUTING.md — public fork-and-own guide. Why PRs are not accepted, how to fork well, what is welcome via issues. - README "Project scope" section — out-of-scope table naming what is fork-and-own territory (web dashboard, fleet policy, runtime firewall, IDE LSP, compliance pack, ticketing, multi-tenancy, ML detectors, marketplace UI, SSO/SCIM/RBAC) with commercial alternatives. - package.json: bugs.url, CONTRIBUTING/SECURITY/CHANGELOG in files whitelist for npm publishing. Changed: - SECURITY.md rewritten. Supported-versions table from stale 5.1.x to current reality (7.3.x active, 7.0-7.2 best-effort, <7.0 EOL). Best-effort solo response timeline. Scope expanded to bin/. - Scanner VERSION constants synced to plugin version. Was 6.0.0 in dashboard-aggregator and posture-scanner. - package.json repository.url corrected from fromaitochitta/ to open/. - README "Feedback & contributing" links to CONTRIBUTING.md. Fixed: - pre-compact-scan size-cap timing test ceiling raised 500ms -> 1000ms. Was a flake on Intel Mac and CI under load. Design target unchanged (<500ms, documented in CLAUDE.md). Notes: - First patch on the stabilization line (post-2026-05-01). - Wave E attack-simulator scenarios deferred indefinitely; coverage remains at 72. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
161 lines
6.5 KiB
Markdown
161 lines
6.5 KiB
Markdown
# 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
|
|
|
|
Issues are tracked on the canonical Forgejo repo:
|
|
`https://git.fromaitochitta.com/open/claude-code-llm-security`
|
|
|
|
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.
|