chore: harden secret-leak prevention

Author: erpic

.pre-commit-config.yaml

@@ -24,3 +24,8 @@ repos:
       - id: check-yaml
       - id: check-added-large-files
       - id: check-merge-conflict
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks

CHANGELOG.md

@@ -1,11 +1,17 @@
-we don# Changelog
+# Changelog
 
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Added
+
+- `docs/private-repo.md` — "Protecting secrets in your overlay" section covering GitHub push protection (server-side block that survives `--no-verify`), a gitleaks pre-commit hook, and a one-time trufflehog history sweep. Aimed at overlay maintainers whose configs reference Slack tokens, LLM API keys, and OAuth client secrets via `{ENV_VAR}` placeholders.
+- `slack-agents init` now prints a visible "SECURITY: protect your secrets before pushing" banner at the end of scaffolding, linking to the new docs section.
+- `SECURITY.md` — pointer for overlay maintainers to the overlay security guidance.
+
 ## [0.8.1] - 2026-05-07
 
 ### Fixed
@@ -101,15 +107,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ### Added
 
-- `slack-agents init` now generates `.gitignore` 
+- `slack-agents init` now generates `.gitignore`
 - `.env.example` template includes comments explaining where to get each token and links to setup guide
 - `build-docker` lists required environment variables after build completes
 - `build-docker` errors if `req*.txt` files are found (dependencies must be in `pyproject.toml`)
 - `init` warns when `req*.txt` files are found with migration instructions
 
 ### Changed
 
-- `pyproject.toml` template uses `python-slack-agents<2` (no minimum pin) 
+- `pyproject.toml` template uses `python-slack-agents<2` (no minimum pin)
 - Setup flow uses venv-first approach: create venv, install package, then `slack-agents init`
 - Updated README, docs/setup.md, and docs/private-repo.md with new setup flow
 

SECURITY.md

@@ -7,3 +7,7 @@ Please report security vulnerabilities privately using [GitHub's security adviso
 Do **not** open public issues for security concerns.
 
 We will acknowledge reports within 72 hours and aim to release fixes promptly.
+
+## For overlay maintainers
+
+If you operate an overlay repository (your own `agents/`, `src/`, and configs built on top of this framework), see [Protecting secrets in your overlay](docs/private-repo.md#protecting-secrets-in-your-overlay) for the recommended setup: GitHub push protection, a gitleaks pre-commit hook, and a one-time trufflehog history sweep.

docs/private-repo.md

@@ -79,3 +79,50 @@ No custom Dockerfile needed — `python-slack-agents` bundles one that auto-dete
 slack-agents build-docker agents/my-agent
 slack-agents build-docker agents/my-agent --push registry.example.com
 ```
+
+## Protecting secrets in your overlay
+
+Overlay configs reference secrets via `{ENV_VAR}` placeholders — Slack tokens, LLM API keys, and OAuth client secrets. The scaffolded `.gitignore` keeps `.env` out of git, but that's a single layer. A few minutes of setup adds defense in depth.
+
+### 1. Enable GitHub push protection
+
+GitHub refuses pushes that contain known provider tokens (Slack `xoxb-`/`xapp-`, Anthropic `sk-ant-`, OpenAI `sk-`, AWS, etc.) before they ever reach the remote. It cannot be bypassed by `git commit --no-verify` — the check runs server-side. Free on public repos, and included in GitHub Advanced Security on private/organisation repos.
+
+Toggle it in **Settings → Code security → Secret scanning** (enable both *Secret scanning* and *Push protection*), or in one shot via the CLI:
+
+```bash
+gh api -X PATCH repos/<org>/<repo> --input - <<'EOF'
+{
+  "security_and_analysis": {
+    "secret_scanning": {"status": "enabled"},
+    "secret_scanning_push_protection": {"status": "enabled"},
+    "secret_scanning_non_provider_patterns": {"status": "enabled"}
+  }
+}
+EOF
+```
+
+### 2. Add a gitleaks pre-commit hook
+
+Catches secrets on the developer's machine before they ever reach a remote — useful as a first line of defense and as the only layer for contributors who fork the repo. Add to your overlay's `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1   # pin to a tag; bump via `pre-commit autoupdate`
+    hooks:
+      - id: gitleaks
+```
+
+Then run `pre-commit install` once per clone. Pre-commit requires a pinned `rev` for reproducibility and supply-chain safety. Keep it fresh either by running `pre-commit autoupdate` periodically or by adding a `package-ecosystem: "pre-commit"` entry to `.github/dependabot.yml` so Dependabot opens hook-bump PRs.
+
+### 3. Sweep history once
+
+Before turning the layers above on, check whether anything already leaked. Trufflehog walks every commit in your history and reports candidate secrets:
+
+```bash
+docker run --rm -v "$PWD:/repo" trufflesecurity/trufflehog:latest \
+  git file:///repo --no-update
+```
+
+If trufflehog finds a real secret, **rotate it immediately** at the issuer (Slack, Anthropic, OpenAI, etc.). Rewriting git history with `git-filter-repo` is optional — once a token has been pushed publicly, assume it's compromised and prioritise rotation over removal.

llms-full.txt

@@ -1309,3 +1309,50 @@ No custom Dockerfile needed — `python-slack-agents` bundles one that auto-dete
 slack-agents build-docker agents/my-agent
 slack-agents build-docker agents/my-agent --push registry.example.com
 ```
+
+## Protecting secrets in your overlay
+
+Overlay configs reference secrets via `{ENV_VAR}` placeholders — Slack tokens, LLM API keys, and OAuth client secrets. The scaffolded `.gitignore` keeps `.env` out of git, but that's a single layer. A few minutes of setup adds defense in depth.
+
+### 1. Enable GitHub push protection
+
+GitHub refuses pushes that contain known provider tokens (Slack `xoxb-`/`xapp-`, Anthropic `sk-ant-`, OpenAI `sk-`, AWS, etc.) before they ever reach the remote. It cannot be bypassed by `git commit --no-verify` — the check runs server-side. Free on public repos, and included in GitHub Advanced Security on private/organisation repos.
+
+Toggle it in **Settings → Code security → Secret scanning** (enable both *Secret scanning* and *Push protection*), or in one shot via the CLI:
+
+```bash
+gh api -X PATCH repos/<org>/<repo> --input - <<'EOF'
+{
+  "security_and_analysis": {
+    "secret_scanning": {"status": "enabled"},
+    "secret_scanning_push_protection": {"status": "enabled"},
+    "secret_scanning_non_provider_patterns": {"status": "enabled"}
+  }
+}
+EOF
+```
+
+### 2. Add a gitleaks pre-commit hook
+
+Catches secrets on the developer's machine before they ever reach a remote — useful as a first line of defense and as the only layer for contributors who fork the repo. Add to your overlay's `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1   # pin to a tag; bump via `pre-commit autoupdate`
+    hooks:
+      - id: gitleaks
+```
+
+Then run `pre-commit install` once per clone. Pre-commit requires a pinned `rev` for reproducibility and supply-chain safety. Keep it fresh either by running `pre-commit autoupdate` periodically or by adding a `package-ecosystem: "pre-commit"` entry to `.github/dependabot.yml` so Dependabot opens hook-bump PRs.
+
+### 3. Sweep history once
+
+Before turning the layers above on, check whether anything already leaked. Trufflehog walks every commit in your history and reports candidate secrets:
+
+```bash
+docker run --rm -v "$PWD:/repo" trufflesecurity/trufflehog:latest \
+  git file:///repo --no-update
+```
+
+If trufflehog finds a real secret, **rotate it immediately** at the issuer (Slack, Anthropic, OpenAI, etc.). Rewriting git history with `git-filter-repo` is optional — once a token has been pushed publicly, assume it's compromised and prioritise rotation over removal.

src/slack_agents/cli/init.py

@@ -107,3 +107,18 @@ def execute(args):
     print("  cp .env.example .env                      # add your tokens")
     print("  pip install -r requirements.txt           # install the framework")
     print("  slack-agents run agents/hello-world       # run the example agent")
+    print()
+    print("=" * 70)
+    print("  SECURITY: protect your secrets before pushing")
+    print("=" * 70)
+    print("  Your config.yaml will reference Slack tokens and LLM API keys")
+    print("  via {ENV_VAR} placeholders. The scaffolded .gitignore keeps")
+    print("  .env out of git, but that is one layer. Before your first push,")
+    print("  enable GitHub push protection and add a gitleaks pre-commit hook.")
+    print()
+    print("  Full guide:")
+    print(
+        "  https://github.com/CompareNetworks/python-slack-agents/blob/main/"
+        "docs/private-repo.md#protecting-secrets-in-your-overlay"
+    )
+    print("=" * 70)