chore(llm-security): v7.3.1 — stabilization patch for forkers and downstream users
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>
This commit is contained in:
Kjell Tore Guttormsen
parent
4bd7cd5056
commit
62a9335772
12 changed files with 336 additions and 30 deletions
161
plugins/llm-security/CONTRIBUTING.md
Normal file
161
plugins/llm-security/CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,161 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue