open-sourcing
This skill should be used when the user asks to "open source this project", "prepare this repository for public release", "make this repo public", "check open-source readiness", "choose a license for this project", or "set up release automation" ahead of a public launch. Provides
Install
npx skills add https://github.com/trailofbits/skills/tree/main/plugins/open-sourcing/skills/open-sourcing
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install trailofbits-skills@llmmart
git clone https://github.com/trailofbits/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole trailofbits/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Open-Sourcing a Repository
Prepare a repository for public release so that an outsider with no prior context can build, use, and contribute to it — and so that nothing sensitive ships with it. Work through the steps in order; the secrets audit comes first because its outcome (keeping vs. recreating the repository) affects everything after it.
When to Use
- Making a private repository public
- Auditing an existing public repository for release quality ("make it official")
- Choosing a license for a project
- Setting up packaging, versioning, or release automation ahead of a public launch
When NOT to Use
- Routine development on an already-released project (no release event)
- Auditing third-party code for vulnerabilities (use a security-review skill)
- Publishing a package from a repository that will stay private — only the release-management steps apply; skip the rest
Workflow
Step 1: Detect the organization profile
bash {baseDir}/scripts/detect_org.sh
The script inspects git remotes and recent committer emails, and prints a
profile name. If it prints trailofbits, read
references/trailofbits.md now and apply its
license policy, publishing accounts, and process notes throughout the
remaining steps. If it prints generic, proceed with the generic guidance
alone. If the user says the detection is wrong, trust the user.
Step 2: Audit for secrets — before anything else
A repository that has ever contained secrets (API keys, credentials, client data) should not be flipped public. History rewriting is error-prone and does not reach forks, caches, or CI artifacts. The reliable fix is a fresh repository: copy the current tree over, commit, and archive the old repository privately.
- Ask whether the project ever handled secrets or client-confidential material. For a security consultancy's tooling, also ask whether test fixtures or example data came from client engagements.
- Scan the full history with a dedicated tool if available —
gitleaks git .ortrufflehog git file://.— rather than eyeballing. - Check beyond the git tree: GitHub Actions logs and artifacts, old releases, issue and PR history, and the repository wiki all become public with the repository.
- After going public, enable GitHub secret scanning and push protection in the repository settings.
Reject these rationalizations — this is the one step that cannot be fixed after publication:
- "The key was revoked, so the history is fine." Revoked credentials still leak infrastructure names, internal URLs, and patterns attackers use for targeting.
- "We'll rewrite history with git-filter-repo." Rewrites miss forks, clones, caches, and CI artifacts; the fresh-repository approach does not.
- "It's only test data." Fixtures derived from client engagements or production systems are confidential regardless of how they are labeled.
Step 3: Run the readiness check
bash {baseDir}/scripts/check_readiness.sh
The script prints a checklist of presence indicators (README, LICENSE, CONTRIBUTING, SECURITY.md, CI, tests, semver tags, ...) and warns about tracked files that commonly contain secrets. Treat unchecked items as discussion prompts, not hard failures — a research prototype does not need everything a flagship library needs. Walk through the gaps with the user and fix the ones that matter for this project.
Step 4: Documentation
The README is the project's front door. Confirm it explains:
- What the project is and what problem it solves (first paragraph)
- How to install it — package manager, container image, or build from source; a fresh-clone build must work using only what is in the repository
- How to use it — at least one concrete, copy-pasteable example
- How to contribute — inline or via
CONTRIBUTING.md - The license — a short section naming it
Also add:
SECURITY.mdwith vulnerability-reporting instructions (a contact address or GitHub private vulnerability reporting). For security tooling this is table stakes.- API documentation, built and hosted (GitHub Pages via CI is the usual route), linked from the README and the repository website field. See the language references below for per-ecosystem doc tooling.
- A code of conduct if the project expects outside contributors.
Step 5: Licensing
No license means not open source, regardless of visibility. Read references/licensing.md for selection criteria and mechanics. The short version:
- Apply the organization's policy if one was detected in Step 1.
- Otherwise: Apache 2.0 as the permissive default, AGPLv3 when private modification by competitors is a real concern, Creative Commons for non-code artifacts.
- Add the
LICENSEfile, set SPDX identifiers in package metadata, state the license in the README, and verify all three agree.
Step 6: Tests and CI
- Confirm the test suite exists and passes; a public repository with a failing default branch signals abandonment.
- Ensure CI runs the tests on every PR, across the supported language-version and platform matrix.
- Enforce formatting and linting in CI (per-language tooling in the references below), so style debates never reach review.
- Respect existing tooling. Do not replace a working formatter, linter, or type checker as part of open-sourcing. If it lags the current generation (the language references name the current tools), warn the maintainer and let them decide; only when a category is missing entirely — no type checker, no formatter — add the current default.
- Consider a coverage gate that fails CI when coverage drops.
- Harden the workflows themselves before they become public attack surface:
- Pin third-party actions to full commit SHAs; enable Dependabot for
github-actionsso pins stay current. - Set least-privilege
permissions:blocks (start frompermissions: {}). - Audit with
zizmor .github/workflows/and lint withactionlint.
- Pin third-party actions to full commit SHAs; enable Dependabot for
Step 7: Repository settings
- Branch protection on the default branch: no force pushes, PRs required. Prefer rulesets for new repositories; classic branch protection remains supported.
- Merge protection: required status checks so PRs cannot merge with failing tests.
- Dependabot or Renovate for dependency and Actions updates. Group updates to cut PR noise, and set a cooldown window (e.g., 7 days) so freshly published — and occasionally hijacked — versions age before adoption.
.editorconfigso contributors' editors agree on whitespace basics.- Labels: create them as soon as more than one issue or PR needs one;
prefixes for facets scale well (
C:component,P:platform). See blight's labels for a worked example.
Step 8: Releases and versioning
- Tag every release
vX.Y.Z, following semver; use-rc.N/-pre.Nsuffixes for release candidates and prereleases. - Make releases CI-driven: pushing a tag (or publishing a GitHub Release)
triggers build, packaging, and upload with no manual steps. A release
should be
git tag vX.Y.Z && git push origin vX.Y.Z. - Publish packages under an organization-owned account, not a personal one, and use trusted publishing (OIDC) instead of long-lived tokens wherever the index supports it.
Step 9: Language-specific practices
Identify the project's languages from its marker files and read the matching reference for packaging, publishing, and quality tooling:
| Marker file | Reference |
|---|---|
pyproject.toml, setup.py |
references/python.md — defers to the modern-python skill for tooling |
CMakeLists.txt, Makefile (C/C++) |
references/c-cpp.md |
Cargo.toml |
references/rust.md |
go.mod |
references/go.md |
package.json |
references/javascript.md |
Gemfile, *.gemspec |
references/ruby.md |
For other ecosystems, apply the cross-cutting principles: reproducible builds from a fresh clone, CI-driven releases, trusted publishing or organization-owned accounts, and license metadata in the package manifest.
Final Review
Before the visibility switch is flipped, verify from an outsider's perspective:
- Clone into a clean directory and follow the README's build instructions verbatim — do they work with no tribal knowledge?
- Re-run
{baseDir}/scripts/check_readiness.shand confirm the remaining gaps are deliberate choices, stated to the user. - Confirm the secrets audit (Step 2) actually happened; it is the one step that cannot be fixed after publication.
Making the repository public is then a repository-settings change. Pair the release with an announcement where the organization has a process for one.
Additional Resources
Reference Files
- references/licensing.md — license selection criteria, SPDX metadata, forks and relicensing
- references/trailofbits.md — Trail of Bits policy overlay (loaded only when detected in Step 1)
- references/python.md, references/c-cpp.md, references/rust.md, references/go.md, references/javascript.md, references/ruby.md — per-language packaging, publishing, and quality tooling
Scripts
scripts/detect_org.sh— prints the organization profile (trailofbitsorgeneric) from git remotes and committer emailsscripts/check_readiness.sh— prints presence indicators for release-readiness files and flags tracked files that commonly hold secrets
Files (skills)
-
references
-
c-cpp.md 2.4 KB
# C/C++ Release Practices ## Build system Use modern CMake. For new projects, [cmake-init](https://github.com/friendlyanon/cmake-init) generates a well-structured project with presets, warnings, and packaging support: ```sh git init && cmake-init <project-name> ``` Plain GNU Make is acceptable for small projects; anything intended for downstream packaging (vcpkg, distro packages) should use CMake. ## Language standard and portability - Use **C++17 as the minimum** for new code; prefer C++20 or newer where the supported toolchains allow. - Write standard C++, not compiler-specific dialects. Limit extensions to those with broad support across Clang, GCC, and (if targeted) MSVC, and build in CI with more than one compiler to keep the code honest. ## Testing and quality engineering - **Unit tests:** [GoogleTest](https://github.com/google/googletest), run through CTest for build-system integration. - **Sanitizers in CI:** build and run the test suite under ASan and UBSan at minimum; add TSan for concurrent code. Sanitizer CI jobs catch memory bugs reviewers miss. - **Valgrind** remains useful for leak detection where sanitizers cannot run. - **Fuzzing:** for code that parses untrusted input, add libFuzzer or AFL++ harnesses, and consider [OSS-Fuzz](https://github.com/google/oss-fuzz) enrollment once public. - Enable a strict warning baseline (`-Wall -Wextra`, warnings-as-errors in CI). ## Formatting and linting Use the latest stable **clang-format** and **clang-tidy**, each enforced in CI. Defaults are fine; a repository may commit its own `.clang-format` and `.clang-tidy` configurations. Examples: [pe-parse](https://github.com/trailofbits/pe-parse/blob/master/.clang-format), [winchecksec](https://github.com/trailofbits/winchecksec/blob/master/.clang-format). ## Documentation [Doxygen](https://www.doxygen.nl/) for API documentation, published to GitHub Pages from CI. ## Packaging and distribution - **vcpkg** is the most common route for distributing C++ libraries; Conan is a reasonable alternative if the audience already uses it. - For tools, attach prebuilt binaries to GitHub Releases from CI, and consider a container image. Keep images small: multi-stage builds with a minimal base (alpine, distroless). - See [pe-parse's release workflow](https://github.com/trailofbits/pe-parse/blob/master/.github/workflows/release.yml) for an example of CI-managed release packaging. -
go.md 2.4 KB
# Go Release Practices Use the standard `go` toolchain for everything. ## Module setup - Initialize with the canonical repository path: `go mod init github.com/<org>/<project>`. The module path is the import path, so set it correctly before anyone depends on the project. - Set the `go` directive in `go.mod` to the latest stable release for greenfield code. ## Project layout - `cmd/<appname>/main.go` for each binary entry point. - `internal/` for packages that must not be imported by other modules — use it liberally; exporting a package is an API commitment. - Do not create a `pkg/` directory reflexively; the [official module layout guidance](https://go.dev/doc/modules/layout) recommends putting importable packages at the repository root unless there is a concrete conflict. - Keep packages focused on a single responsibility, handle every error, and reserve `panic` for unrecoverable states. Follow [Effective Go](https://go.dev/doc/effective_go) and the [Go style guide](https://google.github.io/styleguide/go/). ## Testing, formatting, and linting - `go test ./...` in CI, with `-race` enabled — the race detector is cheap insurance for any code with goroutines. - `gofmt` (or `go fmt`) before committing; enforce in CI. - [golangci-lint](https://golangci-lint.run/) with a committed configuration. - [govulncheck](https://go.dev/blog/vuln) in CI to flag known-vulnerable dependencies actually reachable from the code. ## Documentation Write doc comments for every exported identifier — complete sentences beginning with the identifier name. [pkg.go.dev](https://pkg.go.dev/) renders them automatically once the module is public and tagged. ## Publishing and releases - There is no central upload step: pushing a semver tag (`vX.Y.Z`) to the public repository *is* publishing. The module proxy and pkg.go.dev pick it up automatically. See [developing modules](https://go.dev/doc/modules/developing). - Because tags are immutable once fetched through the module proxy, never retag; publish a new patch version instead. - For binaries, use [goreleaser](https://goreleaser.com/) to build multi-platform artifacts, generate release notes from commits, and attach everything to the GitHub Release on each tag. Consider GitHub [artifact attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations) for provenance on released binaries. -
javascript.md 1.5 KB
# JavaScript/TypeScript Release Practices ## Supported versions Support the active and maintenance Node.js LTS lines, and declare the floor in `engines.node`. Dropping an EOL Node version is routine maintenance. ## Package metadata - Set `license` (SPDX identifier), `repository`, and `engines` in `package.json`; registries and tooling surface these directly. - Commit the lockfile (`package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`) so fresh clones build reproducibly. - Publish under an npm **organization scope** (`@org/package`) rather than a personal account so ownership survives maintainer turnover. ## Formatting, linting, and type checking Keep an existing ESLint + Prettier or Biome setup; if none exists, add Biome (a single tool) or ESLint + Prettier, and enforce them in CI. For TypeScript, run `tsc --noEmit` in CI even when a bundler performs the builds — bundlers typically skip type checking. ## Documentation [TypeDoc](https://typedoc.org/) generates API documentation from TypeScript sources; publish it to GitHub Pages from CI and link it from the README. ## Publishing to npm - Use npm [trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC from GitHub Actions or GitLab CI, generally available since July 2025) instead of long-lived tokens. - Under trusted publishing, the npm CLI publishes **provenance attestations by default** — no `--provenance` flag needed. - Run `npm audit` (or the equivalent for pnpm/yarn) in CI to flag dependencies with known advisories. -
licensing.md 4.3 KB
# Choosing and Applying an Open-Source License A repository is not open source until it has a license. Without one, default copyright applies and nobody can legally use, modify, or redistribute the code regardless of it being publicly visible. ## Decision criteria Choose a license based on the answers to these questions, in order: 1. **Does the organization have a license policy?** Apply it. If an organization profile was loaded in Step 1 of the workflow, its policy takes precedence over the generic guidance below. 2. **Is this software at all?** Datasets, detection rulesets, documentation, and publications are often better served by Creative Commons licenses than software licenses. 3. **Would competitors gain a significant advantage by modifying this work without contributing changes back?** If yes, a network-copyleft license (AGPLv3) protects against service providers privatizing improvements. 4. **Do the project's dependencies constrain the choice?** A project that statically links GPL code cannot be released under a permissive license. Check dependency licenses before deciding. 5. **What does the ecosystem expect?** Libraries intended for broad adoption (especially ones businesses must get legal approval to use) see far more uptake under permissive licenses. ## Common choices | License | Type | Choose when | |---------|------|-------------| | [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) | Permissive | Default for libraries and tools; includes an explicit patent grant, which MIT lacks | | [MIT](https://opensource.org/license/mit) | Permissive | Maximum simplicity; ecosystem convention (e.g., much of npm) | | [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html) | Network copyleft | The project offers competitors a significant advantage if modified privately, including as a hosted service | | [GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html) | Copyleft | Copyleft desired but the network-use clause is not needed | | [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) | Share-alike (non-software) | Publications and documentation; allows commercial use with attribution | | [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) | Non-commercial (non-software) | Rulesets or datasets where commercial use should require a separate agreement | Avoid novel, custom, or "source-available" licenses (BSL, custom non-competes) unless legal counsel is driving that decision; they create adoption friction and are not open source under the [OSD](https://opensource.org/osd). ## Applying the license Choosing is half the job. Then: - **Add a `LICENSE` file** at the repository root containing the full license text. For Apache 2.0, fill in the copyright notice; for CC licenses, link the legal code and state the license clearly in the README. - **Set the license in package metadata** using SPDX identifiers so package indexes display it correctly: - Python: `license = "Apache-2.0"` (SPDX expression, PEP 639) in `pyproject.toml` - Rust: `license = "Apache-2.0"` in `Cargo.toml` - Ruby: `spec.license = "Apache-2.0"` in the gemspec - Node: `"license": "Apache-2.0"` in `package.json` - **State the license in the README**, typically a short section at the end. - **Keep all of these consistent.** A `LICENSE` file that says AGPLv3 with `pyproject.toml` metadata that says MIT is a real (and common) bug. ## Copyright lines A copyright line uses the current year only; open-ended ranges ("2020-present") add nothing legally: ``` Copyright (c) 2026 Example Org <opensource@example.org> ``` ## Forks and adopted projects When taking over maintenance of an existing open-source project: - **Keep the existing license** and add a copyright line for the new maintainer below the original: ``` Copyright (c) 2019 John Q. Public <john@example.com> Copyright (c) 2026 Example Org <opensource@example.org> ``` - **Do not relicense** unless every copyright holder agrees or the original license explicitly permits it. Permissively licensed projects may be *re-released* under a stronger license for new contributions, but the original code remains under its original terms and the original notices must be preserved. When in doubt about any licensing question, consult whoever handles legal or open-source policy for the organization before publishing. -
python.md 5 KB
# Python Release Practices For project scaffolding, dependency management (uv), formatting/linting (ruff), and type checking (ty), use the **modern-python skill** from this marketplace — do not duplicate its guidance. If that skill is not installed, apply the toolchain directly with standard configurations: uv for dependencies and builds, `ruff format`/`ruff check` for style, ty for type checking (note: ty is pre-1.0 with breaking changes between releases — pin a version rather than an open floor), pytest for tests. Per the tooling principle in SKILL.md Step 6: leave an existing working toolchain in place, warning the maintainer about the current equivalents (black → `ruff format`, mypy → ty, pre-commit → prek); adopt the modern tools only for categories the project lacks entirely. This file covers only what the modern-python skill does not: supported-version policy, documentation, and publishing. ## Supported Python versions - Greenfield projects: target the latest stable Python. - If broader compatibility is needed, use the **N-3 rule**: support no more than three minor versions behind current (e.g., with 3.14 current, the floor is 3.11). Declare the floor with `requires-python` in `pyproject.toml` and test the full range in CI. ## Documentation - **API docs:** [pdoc](https://github.com/mitmproxy/pdoc) — note *pdoc*, not *pdoc3*, which is a hostile fork. - **Full documentation sites:** [Sphinx](https://www.sphinx-doc.org/) with the [furo](https://github.com/pradyunsg/furo) theme, or [MkDocs with Material](https://squidfunk.github.io/mkdocs-material/). - Deploy to GitHub Pages from CI ([actions/deploy-pages](https://github.com/actions/deploy-pages) or [actions-gh-pages](https://github.com/peaceiris/actions-gh-pages)) and link the site from the README and the repository's website field. ## Packaging `pyproject.toml` is the only packaging file needed unless building native CPython extensions (`setup.py` for C, maturin/`Cargo.toml` for Rust). Build distributions with `uv build`. ## Publishing to PyPI Use [trusted publishing](https://docs.pypi.org/trusted-publishers/) — an OIDC trust relationship between PyPI and the GitHub Actions workflow — instead of API tokens. Configure it on PyPI under the project's publishing settings, restricted to a dedicated `pypi` environment in the repository. Example release workflow. Actions are pinned to full commit SHAs per the CI hardening notes in SKILL.md; the SHAs below correspond to the tags in the trailing comments and will drift — resolve current ones before use, and let Dependabot keep them updated: ```yaml name: release on: release: types: [published] permissions: {} jobs: build: name: Build distributions runs-on: ubuntu-latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0 - name: Build distributions run: uv build - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: name: distributions path: dist/ provenance: name: Generate SLSA provenance runs-on: ubuntu-latest needs: [build] permissions: id-token: write attestations: write steps: - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 with: name: distributions path: dist/ - uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1 with: subject-path: dist/* publish: name: Publish to PyPI runs-on: ubuntu-latest needs: [build, provenance] environment: name: pypi permissions: id-token: write # required for trusted publishing and attestations steps: - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 with: name: distributions path: dist/ - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1 with: attestations: true ``` `attestations: true` generates [PEP 740](https://peps.python.org/pep-0740/) publish attestations — the default since gh-action-pypi-publish v1.11, kept explicit here for clarity — and the provenance job attaches [SLSA build provenance](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations) to the built distributions. ## Quality extras worth adding before release - Property-based tests with [Hypothesis](https://hypothesis.readthedocs.io/) for parsing- or algorithm-heavy code (see the property-based-testing skill in this marketplace). - Docstring coverage enforcement with [interrogate](https://interrogate.readthedocs.io/) or ruff's `D` rules so public APIs stay documented as the project grows. - Dependency auditing in CI with `uv audit` (currently in preview) or [pip-audit](https://github.com/pypa/pip-audit). -
ruby.md 1.2 KB
# Ruby Release Practices ## Supported versions Ruby releases a minor version yearly and the community supports roughly the last three. Support those three; going lower buys little and costs CI matrix time. Declare the floor with `required_ruby_version` in the gemspec. ## Dependencies Use [Bundler](https://bundler.io/). Configure it to install into a vendor directory rather than the user's global gem store, and keep that directory out of git: ```sh bundle config set --local path vendor/bundle echo vendor/bundle/ >> .gitignore ``` ## Formatting and linting Use [RuboCop](https://github.com/rubocop/rubocop). The default cops are reasonable; projects commonly relax the metrics cops (method length, complexity) in `.rubocop.yml` rather than fighting them. Enforce in CI. ## Publishing to RubyGems - Publish to [RubyGems.org](https://rubygems.org/). - Use RubyGems [trusted publishing](https://guides.rubygems.org/trusted-publishing/) from GitHub Actions instead of API keys. - Add the organization's shared account as a gem **co-owner** (`gem owner <gem> --add <email>`) so the package survives maintainer turnover. - Set `spec.license` (SPDX identifier) and `spec.metadata` links (`source_code_uri`, `changelog_uri`) in the gemspec. -
rust.md 2.3 KB
# Rust Release Practices Use `cargo` for everything: building, testing (`cargo test`), formatting (`cargo fmt`), linting (`cargo clippy`), and documentation (`cargo doc`). ## Toolchain and edition - Prefer the latest stable compiler and the latest edition for new code. - If older-compiler support matters, declare it explicitly with `package.rust-version` in `Cargo.toml` and test that version in CI. ## Crate-level lints Add these to `lib.rs`/`main.rs` before release: ```rust #![forbid(unsafe_code)] #![deny(missing_docs)] #![deny(rustdoc::broken_intra_doc_links)] ``` - `forbid(unsafe_code)` prevents direct `unsafe` (transitive uses through dependencies are still allowed). Omit only for crates that genuinely need `unsafe`, and isolate those blocks with `// SAFETY:` comments. - `deny(missing_docs)` fails the build when a public API lacks a rustdoc comment. - Optionally forbid explicit panics in library code with `#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]` — but note panics are often appropriate; apply this only where callers need `Result`-based error handling throughout. ## Supply-chain checks - [`cargo audit`](https://github.com/rustsec/rustsec) in CI flags dependencies with known advisories. - [`cargo deny`](https://github.com/EmbarkStudios/cargo-deny) additionally enforces license and source policies on the dependency tree — useful for catching a copyleft dependency slipping into a permissively licensed project. ## Publishing to crates.io - Use crates.io [trusted publishing](https://crates.io/docs/trusted-publishing) (OIDC from GitHub Actions) instead of long-lived API tokens. - [`cargo release`](https://github.com/crate-ci/cargo-release) manages version bumps, tagging, and pushing. A common configuration in `Cargo.toml`, with the actual publish performed by CI: ```toml [package.metadata.release] publish = false # handled by GitHub Actions push = true ``` - Set `license` (SPDX expression), `description`, `repository`, and `documentation` in `Cargo.toml`; crates.io and docs.rs surface these directly. docs.rs builds documentation automatically on publish. ## Binary distribution For tools with end-user binaries, use [cargo-dist](https://github.com/axodotdev/cargo-dist) or [goreleaser](https://goreleaser.com/) to build multi-platform release artifacts and installers from CI on each tag. -
trailofbits.md 3.6 KB
# Trail of Bits Profile Apply this guidance **in addition to** the generic workflow when `scripts/detect_org.sh` prints `trailofbits`. Everything in this file is public information; internal process details (credentials, announcement workflow, release sign-off) live in Trail of Bits' internal documentation, which the maintainer should consult directly. ## License policy - **Default to [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)** for nearly all projects. - **Use [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html)** when the project would offer a significant advantage to competitors who modify it without contributing changes back. - **Use Creative Commons for non-code work:** - [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) for rulesets (e.g., [semgrep-rules](https://github.com/trailofbits/semgrep-rules)) - [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) for publications and informational material (e.g., [publications](https://github.com/trailofbits/publications)) - When in doubt, confirm with the project manager or an existing open-source maintainer before publishing. Copyright line convention (current year only, no ranges): ``` Copyright (c) 2026 Trail of Bits <opensource@trailofbits.com> ``` For forks and adopted projects, add this line under the existing copyright rather than relicensing, unless the changes involve the company's competitive interests (see the AGPLv3 criterion above). ## Repository location Official projects live in the [trailofbits](https://github.com/trailofbits) GitHub organization. Related ecosystems use [lifting-bits](https://github.com/lifting-bits) (binary lifting) and [crytic](https://github.com/crytic) (smart contract tooling). Move personal repositories into the appropriate organization before announcing them. ## Package publishing Publish under the company's shared accounts so ownership survives individual departures: - **PyPI:** add the [trailofbits organization](https://pypi.org/org/trailofbits/) as an owner of the package. - **RubyGems:** add the [trailofbits account](https://rubygems.org/profiles/trailofbits) as a gem co-owner. - Prefer **trusted publishing** (OIDC from GitHub Actions) over long-lived API tokens on every index that supports it (PyPI, RubyGems, crates.io). Account access is handled internally; consult the internal documentation rather than creating parallel accounts. ## Project scaffolding - **Python:** generate new projects with [cookiecutter-python](https://github.com/trailofbits/cookiecutter-python), which encodes current company practices: uv, ruff, ty, prek, pdoc, SHA-pinned CI audited by zizmor, trusted publishing with SLSA provenance, and 100% coverage and docstring-coverage gates. Generated projects also ship `AGENTS.md` agent instructions. The `modern-python` skill in this marketplace covers the same toolchain. - Example repositories for release automation: [pe-parse](https://github.com/trailofbits/pe-parse/blob/master/.github/workflows/release.yml) (C++/CI-managed packaging) and [pip-audit](https://github.com/pypa/pip-audit/blob/main/.github/workflows/release.yml) (Python/trusted publishing). ## Before flipping the repository public Beyond the generic checklist, Trail of Bits maintainers should: 1. Confirm the license choice with their project manager if it deviates from Apache 2.0. 2. Follow the internal public-release checklist and announcement process (blog post, social media) documented internally — public release is often paired with an announcement, and coordinating that before the repository goes public preserves the option.
-
-
scripts
-
check_readiness.sh 2.4 KB
#!/usr/bin/env bash # Reports release-readiness indicators for the current repository. # Informational only: an unchecked item is a discussion prompt, not a # hard failure. Run from the repository root. # -e is intentionally omitted: check commands are expected to fail. set -uo pipefail exists_any() { local f for f in "$@"; do [ -e "$f" ] && return 0 done return 1 } check() { local label="$1" shift if "$@" >/dev/null 2>&1; then printf ' [x] %s\n' "$label" else printf ' [ ] %s\n' "$label" fi } has_ci_workflows() { exists_any .github/workflows/*.yml .github/workflows/*.yaml } has_dependency_updates() { exists_any .github/dependabot.yml .github/dependabot.yaml \ renovate.json renovate.json5 .github/renovate.json .github/renovate.json5 } has_tests() { exists_any tests test spec || git ls-files 2>/dev/null | grep -E '(_test\.(go|py|rb)$|\.test\.(ts|js|tsx|jsx)$|_spec\.rb$)' >/dev/null } has_semver_tags() { git tag --list 'v[0-9]*' 2>/dev/null | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+' >/dev/null } list_suspicious_files() { git ls-files 2>/dev/null | grep -iE '(^|/)(\.env(\..+)?|.*\.pem|.*\.p12|.*\.pfx|.*\.keystore|id_(rsa|dsa|ecdsa|ed25519).*|.*credentials.*\.(json|xml|yml|yaml))$' | grep -vE '\.(example|sample|template)(\.|$)' } main() { if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then echo "error: not inside a git repository" >&2 exit 1 fi echo "Release-readiness indicators:" check "README" exists_any README.md README.rst README.txt README check "LICENSE" exists_any LICENSE LICENSE.md LICENSE.txt COPYING COPYING.md check "CONTRIBUTING" exists_any CONTRIBUTING.md CONTRIBUTING.rst .github/CONTRIBUTING.md check "SECURITY policy" exists_any SECURITY.md .github/SECURITY.md check "Code of conduct" exists_any CODE_OF_CONDUCT.md .github/CODE_OF_CONDUCT.md check ".gitignore" exists_any .gitignore check ".editorconfig" exists_any .editorconfig check "CI workflows" has_ci_workflows check "Automated dependency updates (Dependabot/Renovate)" has_dependency_updates check "Tests" has_tests check "Semver release tags (vX.Y.Z)" has_semver_tags local suspicious suspicious=$(list_suspicious_files) if [ -n "${suspicious}" ]; then echo echo "WARNING: tracked files that commonly contain secrets:" printf '%s\n' "${suspicious}" | sed 's/^/ - /' echo "Review these (and full history) before making the repository public." fi } main "$@" -
detect_org.sh 741 B
#!/usr/bin/env bash # Detects whether the current repository belongs to an organization with an # additional guidance profile in references/. Prints the profile name # ("trailofbits" or "generic") to stdout. set -euo pipefail TOB_ORGS='trailofbits|lifting-bits|crytic' remote_matches_tob() { git remote -v 2>/dev/null | grep -qiE "github\.com[:/](${TOB_ORGS})/" } commits_match_tob() { git log --format='%ae%n%ce' -n 200 2>/dev/null | grep '@trailofbits\.com$' >/dev/null } main() { if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then echo "error: not inside a git repository" >&2 exit 1 fi if remote_matches_tob || commits_match_tob; then echo "trailofbits" else echo "generic" fi } main "$@"
-
-
SKILL.md 10.2 KB
--- name: open-sourcing description: This skill should be used when the user asks to "open source this project", "prepare this repository for public release", "make this repo public", "check open-source readiness", "choose a license for this project", or "set up release automation" ahead of a public launch. Provides a release-readiness workflow covering secrets hygiene, licensing, documentation, CI, and language-specific packaging. --- # Open-Sourcing a Repository Prepare a repository for public release so that an outsider with no prior context can build, use, and contribute to it — and so that nothing sensitive ships with it. Work through the steps in order; the secrets audit comes first because its outcome (keeping vs. recreating the repository) affects everything after it. ## When to Use - Making a private repository public - Auditing an existing public repository for release quality ("make it official") - Choosing a license for a project - Setting up packaging, versioning, or release automation ahead of a public launch ## When NOT to Use - Routine development on an already-released project (no release event) - Auditing third-party code for vulnerabilities (use a security-review skill) - Publishing a package from a repository that will stay private — only the release-management steps apply; skip the rest ## Workflow ### Step 1: Detect the organization profile ```sh bash {baseDir}/scripts/detect_org.sh ``` The script inspects git remotes and recent committer emails, and prints a profile name. If it prints `trailofbits`, read [references/trailofbits.md](references/trailofbits.md) now and apply its license policy, publishing accounts, and process notes throughout the remaining steps. If it prints `generic`, proceed with the generic guidance alone. If the user says the detection is wrong, trust the user. ### Step 2: Audit for secrets — before anything else A repository that has **ever** contained secrets (API keys, credentials, client data) should not be flipped public. History rewriting is error-prone and does not reach forks, caches, or CI artifacts. The reliable fix is a fresh repository: copy the current tree over, commit, and archive the old repository privately. 1. Ask whether the project ever handled secrets or client-confidential material. For a security consultancy's tooling, also ask whether test fixtures or example data came from client engagements. 2. Scan the full history with a dedicated tool if available — `gitleaks git .` or `trufflehog git file://.` — rather than eyeballing. 3. Check beyond the git tree: GitHub Actions logs and artifacts, old releases, issue and PR history, and the repository wiki all become public with the repository. 4. After going public, enable GitHub secret scanning and push protection in the repository settings. Reject these rationalizations — this is the one step that cannot be fixed after publication: - *"The key was revoked, so the history is fine."* Revoked credentials still leak infrastructure names, internal URLs, and patterns attackers use for targeting. - *"We'll rewrite history with git-filter-repo."* Rewrites miss forks, clones, caches, and CI artifacts; the fresh-repository approach does not. - *"It's only test data."* Fixtures derived from client engagements or production systems are confidential regardless of how they are labeled. ### Step 3: Run the readiness check ```sh bash {baseDir}/scripts/check_readiness.sh ``` The script prints a checklist of presence indicators (README, LICENSE, CONTRIBUTING, SECURITY.md, CI, tests, semver tags, ...) and warns about tracked files that commonly contain secrets. Treat unchecked items as discussion prompts, not hard failures — a research prototype does not need everything a flagship library needs. Walk through the gaps with the user and fix the ones that matter for this project. ### Step 4: Documentation The README is the project's front door. Confirm it explains: - **What the project is** and what problem it solves (first paragraph) - **How to install it** — package manager, container image, or build from source; a fresh-clone build must work using only what is in the repository - **How to use it** — at least one concrete, copy-pasteable example - **How to contribute** — inline or via `CONTRIBUTING.md` - **The license** — a short section naming it Also add: - **`SECURITY.md`** with vulnerability-reporting instructions (a contact address or GitHub private vulnerability reporting). For security tooling this is table stakes. - **API documentation**, built and hosted (GitHub Pages via CI is the usual route), linked from the README and the repository website field. See the language references below for per-ecosystem doc tooling. - A **code of conduct** if the project expects outside contributors. ### Step 5: Licensing No license means not open source, regardless of visibility. Read [references/licensing.md](references/licensing.md) for selection criteria and mechanics. The short version: 1. Apply the organization's policy if one was detected in Step 1. 2. Otherwise: Apache 2.0 as the permissive default, AGPLv3 when private modification by competitors is a real concern, Creative Commons for non-code artifacts. 3. Add the `LICENSE` file, set SPDX identifiers in package metadata, state the license in the README, and verify all three agree. ### Step 6: Tests and CI - Confirm the test suite exists and passes; a public repository with a failing default branch signals abandonment. - Ensure CI runs the tests on every PR, across the supported language-version and platform matrix. - Enforce formatting and linting in CI (per-language tooling in the references below), so style debates never reach review. - **Respect existing tooling.** Do not replace a working formatter, linter, or type checker as part of open-sourcing. If it lags the current generation (the language references name the current tools), warn the maintainer and let them decide; only when a category is missing entirely — no type checker, no formatter — add the current default. - Consider a coverage gate that fails CI when coverage drops. - Harden the workflows themselves before they become public attack surface: - Pin third-party actions to full commit SHAs; enable Dependabot for `github-actions` so pins stay current. - Set least-privilege `permissions:` blocks (start from `permissions: {}`). - Audit with `zizmor .github/workflows/` and lint with `actionlint`. ### Step 7: Repository settings - **Branch protection** on the default branch: no force pushes, PRs required. Prefer rulesets for new repositories; classic branch protection remains supported. - **Merge protection**: required status checks so PRs cannot merge with failing tests. - **Dependabot or Renovate** for dependency and Actions updates. Group updates to cut PR noise, and set a cooldown window (e.g., 7 days) so freshly published — and occasionally hijacked — versions age before adoption. - **`.editorconfig`** so contributors' editors agree on whitespace basics. - **Labels**: create them as soon as more than one issue or PR needs one; prefixes for facets scale well (`C:` component, `P:` platform). See [blight's labels](https://github.com/trailofbits/blight/labels) for a worked example. ### Step 8: Releases and versioning - Tag every release `vX.Y.Z`, following [semver](https://semver.org/); use `-rc.N` / `-pre.N` suffixes for release candidates and prereleases. - Make releases CI-driven: pushing a tag (or publishing a GitHub Release) triggers build, packaging, and upload with no manual steps. A release should be `git tag vX.Y.Z && git push origin vX.Y.Z`. - Publish packages under an organization-owned account, not a personal one, and use **trusted publishing** (OIDC) instead of long-lived tokens wherever the index supports it. ### Step 9: Language-specific practices Identify the project's languages from its marker files and read the matching reference for packaging, publishing, and quality tooling: | Marker file | Reference | |-------------|-----------| | `pyproject.toml`, `setup.py` | [references/python.md](references/python.md) — defers to the modern-python skill for tooling | | `CMakeLists.txt`, `Makefile` (C/C++) | [references/c-cpp.md](references/c-cpp.md) | | `Cargo.toml` | [references/rust.md](references/rust.md) | | `go.mod` | [references/go.md](references/go.md) | | `package.json` | [references/javascript.md](references/javascript.md) | | `Gemfile`, `*.gemspec` | [references/ruby.md](references/ruby.md) | For other ecosystems, apply the cross-cutting principles: reproducible builds from a fresh clone, CI-driven releases, trusted publishing or organization-owned accounts, and license metadata in the package manifest. ## Final Review Before the visibility switch is flipped, verify from an outsider's perspective: 1. Clone into a clean directory and follow the README's build instructions verbatim — do they work with no tribal knowledge? 2. Re-run `{baseDir}/scripts/check_readiness.sh` and confirm the remaining gaps are deliberate choices, stated to the user. 3. Confirm the secrets audit (Step 2) actually happened; it is the one step that cannot be fixed after publication. Making the repository public is then a repository-settings change. Pair the release with an announcement where the organization has a process for one. ## Additional Resources ### Reference Files - **[references/licensing.md](references/licensing.md)** — license selection criteria, SPDX metadata, forks and relicensing - **[references/trailofbits.md](references/trailofbits.md)** — Trail of Bits policy overlay (loaded only when detected in Step 1) - **[references/python.md](references/python.md)**, **[references/c-cpp.md](references/c-cpp.md)**, **[references/rust.md](references/rust.md)**, **[references/go.md](references/go.md)**, **[references/javascript.md](references/javascript.md)**, **[references/ruby.md](references/ruby.md)** — per-language packaging, publishing, and quality tooling ### Scripts - **`scripts/detect_org.sh`** — prints the organization profile (`trailofbits` or `generic`) from git remotes and committer emails - **`scripts/check_readiness.sh`** — prints presence indicators for release-readiness files and flags tracked files that commonly hold secrets
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.