From 4a1b9eca81cc556cc28583f492d565832130433c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20Contreras=20Guill=C3=A9n?= Date: Fri, 6 Nov 2026 03:03:08 -0800 Subject: [PATCH] docs: add a security policy and a contributing guide The repository is public, so people need to know how to report a vulnerability privately and how to propose a change. SECURITY.md covers the supported versions, GitHub's private vulnerability reporting (now on), what happens after a report, and what is in and out of scope; CONTRIBUTING.md covers issues first, working on a clone without installing devkit, the change, the checks a pull request must pass, commits and pull requests, and the Apache-2.0 inbound terms. The README links both, and Developing devkit now describes the real release flow (dev pr merge, dev release, a check of the published archive) instead of raw commands the guard refuses. --- CHANGELOG.md | 9 ++++++ CONTRIBUTING.md | 74 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 +++ SECURITY.md | 68 +++++++++++++++++++++++++++++++++++++++++ docs/development.md | 18 +++++------ 5 files changed, 163 insertions(+), 10 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/CHANGELOG.md b/CHANGELOG.md index b6ecb9a..bde0b69 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,15 @@ All notable changes to devkit. Versions follow CalVer `YY.MM.PATCH` (PATCH resta ## [Unreleased] +### Added + +- A security policy (`SECURITY.md`) with private vulnerability reporting on GitHub, and a contributing guide + (`CONTRIBUTING.md`), now that the repository is public. + +### Changed + +- The release process in Developing devkit uses `dev pr merge`, `dev release`, and a check of the published archive. + ### Fixed - `dev agents test` reads the hooks log from the byte offset it recorded, so the guard check no longer reports diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..882c439 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,74 @@ +# Contributing to devkit + +Thank you for helping. This guide covers how to propose a change, the checks a pull request must pass, and the +conventions devkit follows. The code layout and the design principles are in +[Developing devkit](docs/development.md). + +## Before you start + +- **A bug or an idea:** open an issue. For a bug, say what you expected, what happened, the devkit version + (`dev version`), your macOS version, and the agent (Claude Code, Codex, Claude Desktop, or the ChatGPT app). +- **A security issue:** never in an issue. Follow the [security policy](SECURITY.md). +- **A larger change** (a new command, a new hook, a change to the guard or the installer): open an issue first, so + you and the maintainers agree on the approach before you write the code. + +## Work on a clone + +devkit is standard-library Python and runs from its folder, so you can change it and run its tests without +installing it: + +```bash +git clone https://github.com/fireflysoftwaresolutions/devkit.git +cd devkit +python3 -m unittest discover -s tests +/usr/bin/python3 -m unittest discover -s tests # Python 3.9, the macOS system Python +bin/dev --help +``` + +Installing devkit (`./install.sh`) changes your agents' global settings, hooks, and instructions under `~/.claude` +and `~/.codex`. Do it only when you want devkit to manage your machine; see [Getting started](docs/getting-started.md). + +## Make the change + +1. Branch from an up-to-date `main`: `/`, for example `fix/guard-quoted-paths`. Types are `feat`, `fix`, + `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, and `deps`; the topic is lowercase kebab-case, and + the whole name is at most 60 characters. +2. Write the test first, and see it fail for the reason you expect. A test must be able to fail for a real bug: + `bin/dev test prove` checks that new tests fail without your change. +3. Keep the design principles: the standard library only, Python 3.9 compatible, hooks that fail open, and a guard + refusal that always names the right way to do the thing. +4. Update the documentation in the same branch, with a command in [Commands](docs/commands.md), a guard rule in + [Guard rules](docs/guard.md), and anything a user notices in the `[Unreleased]` section of the + [CHANGELOG](CHANGELOG.md). +5. To change a crew member, edit `config/crew.json` and run `bin/dev crew sync`. The files in `plugin/agents/` are + generated: never edit them by hand. + +## Run the checks + +Every check must pass before you open the pull request. CI runs the tests on Python 3.9 and 3.13 and a security job. + +| Check | Command | +| --- | --- | +| The tests, on both Pythons | `python3 -m unittest discover -s tests` and `/usr/bin/python3 -m unittest discover -s tests` | +| The code compiles | `python3 -m compileall -q lib bin` | +| No test that cannot fail | `bin/dev test audit tests/` | +| No unfinished work (stubs, placeholders, TODOs without a task) | `bin/dev stubs` | +| The documentation | `bin/dev docs check` (markdownlint, lychee, and Vale) | +| Everything CI runs, locally | `bin/dev ci --run` (the security job needs Docker) | + +## Commits and pull requests + +- Write commit messages as Conventional Commits: `type(scope): summary`, in the imperative, at most 72 characters, + with a body that says why. Make one logical change per commit. +- Do not add AI attribution, such as `Co-Authored-By` lines for tools or "Generated with" lines. +- Fill in every section of the pull request template (what and why, changes, how to verify, risk and rollback, and + links). +- Keep one change per pull request, rebased on `main`. A maintainer merges it after CI passes and a review. + +## License + +devkit is licensed under the [Apache License 2.0](LICENSE). By submitting a contribution, you agree that it is +licensed under the same terms (section 5 of the license) and that you have the right to submit it. + +See also [Developing devkit](docs/development.md), [Commands](docs/commands.md), and the +[security policy](SECURITY.md). diff --git a/README.md b/README.md index d0332f5..3f295ed 100644 --- a/README.md +++ b/README.md @@ -222,3 +222,7 @@ devkit is designed and maintained by **Andrés Contreras Guillén** for **Firefl Copyright © 2026 Firefly Software Solutions Inc. Licensed under the Apache License 2.0; see [LICENSE](LICENSE). Third-party skills and tools installed by devkit keep their own licenses; see [NOTICE](NOTICE). + +Contributions are welcome: the [contributing guide](CONTRIBUTING.md) explains how to propose a change and the checks +a pull request must pass. Report a vulnerability privately, as the [security policy](SECURITY.md) describes, never in +a public issue. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..ab03053 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,68 @@ +# Security policy + +devkit runs inside developers' agent sessions. Its hooks see every tool call, its guard decides what an agent may +run, and its installer writes the agents' settings, hooks, and instructions. A vulnerability in devkit can reach every +machine that installs it, so report it privately, as described here. + +## Supported versions + +| Version | Supported | +| --- | --- | +| The latest release (see [Releases](https://github.com/fireflysoftwaresolutions/devkit/releases)) | Yes | +| Older releases | No: update with `dev update` | + +Fixes ship as a new patch version (CalVer `YY.MM.PATCH`), with notes in the [CHANGELOG](CHANGELOG.md). + +## Report a vulnerability + +Use GitHub's private vulnerability reporting: open the repository's **Security** tab and choose **Report a +vulnerability**, or go straight to +[the new advisory form](https://github.com/fireflysoftwaresolutions/devkit/security/advisories/new). Only you and the +maintainers see the report. + +Do not report a vulnerability in a public issue, pull request, or discussion. + +Include what helps the maintainers reproduce it: + +- the devkit version (`dev version`) and your macOS version; +- the agent and the surface, such as Claude Code in the terminal or in Claude Desktop's Code tab, Codex in the + terminal or the ChatGPT app, or the Claude Desktop extension; +- the steps, the impact you see, and a proof of concept if you have one. + +Redact secrets before you send logs or transcripts: devkit's logs can contain command lines and file paths. + +## What happens next + +1. The maintainers confirm in the advisory that they received the report, and keep you updated there. +2. They reproduce the issue and fix it in the advisory's private fork. +3. They release the fix as a patch version, publish the advisory, and request a CVE when the issue qualifies. +4. The advisory credits you, unless you prefer not to be named. + +## Scope + +In scope: + +- the `dev` CLI and everything under `lib/` and `bin/`; +- the hooks, including the guard: a way to make an agent run what the guard should refuse is a vulnerability; +- the installer (`install.sh`, `dev setup`, `dev install`) and the settings, hooks, and instructions it writes; +- the MCP server (`dev mcp`) and the Claude Desktop extension; +- the dashboard, a generated HTML file: data it shows without escaping is in scope; +- the CI/CD templates that `dev ci init` writes. + +Out of scope: + +- third-party skills, plugins, and tools that devkit installs: report those upstream ([NOTICE](NOTICE) lists their + sources); +- issues in the agents themselves (Claude Code, Codex, Claude Desktop, the ChatGPT app): report those to their + vendors; +- attacks that need an already compromised machine or account. + +## How this repository is protected + +- Secret scanning and push protection are on. +- CI runs a security job on every pull request: gitleaks, Semgrep, osv-scanner, Trivy, and zizmor. +- GitHub Actions are pinned by commit SHA and container images by digest, with least-privilege tokens. +- Dependabot keeps the pinned actions current. +- devkit bundles no third-party code. + +See also [Guard rules](docs/guard.md) and the [contributing guide](CONTRIBUTING.md). diff --git a/docs/development.md b/docs/development.md index 9d6851a..959398e 100644 --- a/docs/development.md +++ b/docs/development.md @@ -114,16 +114,14 @@ devkit follows its own delivery method: integrate locally, run the full suite, p 2. Run the tests on both Pythons (see [Running the tests](#running-the-tests)), `dev docs check` and `dev diagram check docs/diagrams`. 3. Run `dev install` on your machine, then `dev doctor` and `dev agents test`; every check must pass. -4. Push the release branch once, open one PR, and watch CI (`gh pr checks --watch`). -5. Merge, tag, and publish: - - ```bash - git tag -a vYY.MM.PATCH -m "devkit vYY.MM.PATCH" - git push origin vYY.MM.PATCH - gh release create vYY.MM.PATCH --title "devkit vYY.MM.PATCH" --notes-file <(sed -n '/^## \[YY.MM.PATCH\]/,/^## \[/p' CHANGELOG.md | sed '$d') - ``` - -6. Developers update with `dev update`. +4. Run what CI runs (`dev ci --run`), then push the release branch once (`dev push`), open one PR + (`dev pr create`), and watch its CI (`dev pr checks --watch`). +5. Merge with `dev pr merge`, wait for the CI run on `main` (`dev ci status --watch`), and publish with + `dev release`. It tags `vYY.MM.PATCH` on `main` and creates the GitHub release with the CHANGELOG section as its + notes. The guard refuses a raw `gh pr merge` or `gh release create`. +6. Verify what was published: download the source archive into an empty folder + (`gh release download vYY.MM.PATCH --archive tar.gz -D `), compare it with the tag, and run its tests. +7. Developers update with `dev update`. ## Conventions