diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 931d799..f299ab1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,6 +29,49 @@ pre-commit install - Install pre-commit hooks once with `pre-commit install`. - Keep changes small and focused; prefer incremental PRs. +### Recommended: Secret Scanning Pre-commit Hooks + +To prevent accidental commits of API keys, tokens, or other sensitive data (especially in proof artifacts), consider adding secret scanning to your pre-commit configuration: + +#### Option 1: gitleaks (recommended) + +```yaml +# Add to .pre-commit-config.yaml +repos: + - repo: https://github.com/gitleaks/gitleaks + rev: v8.18.0 + hooks: + - id: gitleaks +``` + +#### Option 2: truffleHog + +```yaml +# Add to .pre-commit-config.yaml +repos: + - repo: https://github.com/trufflesecurity/trufflehog + rev: v3.63.0 + hooks: + - id: trufflehog + args: ['--trace', 'filesystem', '.'] +``` + +#### Option 3: detect-secrets + +```yaml +# Add to .pre-commit-config.yaml +repos: + - repo: https://github.com/Yelp/detect-secrets + rev: v1.4.0 + hooks: + - id: detect-secrets + args: ['--baseline', '.secrets.baseline'] +``` + +After adding a secret scanner, run `pre-commit install` again to activate it. The scanner will automatically check files before each commit and block commits containing potential secrets. + +See the [pre-commit hooks documentation](https://pre-commit.com/hooks.html) for more secret scanning options. + ### Common Commands ```bash diff --git a/README.md b/README.md index 335ed30..218e739 100644 --- a/README.md +++ b/README.md @@ -198,6 +198,19 @@ Run the prompts as an MCP server for programmatic access. This option is most us 2. Point the assistant at the generated spec and run `prompts/generate-task-list-from-spec.md` to create the implementation backlog. 3. Use `prompts/manage-tasks.md` while executing work to keep status, demo criteria, and proof artifacts up to date. +## Security Best Practices + +### Protecting Sensitive Data in Proof Artifacts + +Proof artifacts are committed to your repository and may be publicly visible. **Never commit real credentials or sensitive data.** Follow these guidelines: + +- **Replace credentials with placeholders**: Use `[YOUR_API_KEY_HERE]`, `[REDACTED]`, or `example-key-123` instead of real API keys, tokens, or passwords +- **Use example values**: When demonstrating configuration, use dummy or example data instead of production values +- **Sanitize command output**: Review CLI output and logs for accidentally captured credentials before committing +- **Consider pre-commit hooks**: Tools like [gitleaks](https://github.com/gitleaks/gitleaks), [truffleHog](https://github.com/trufflesecurity/truffleHog), or [talisman](https://github.com/thoughtworks/talisman) can automatically scan for secrets before commits + +The SDD workflow prompts include built-in reminders about security, but ultimate responsibility lies with the developer to review artifacts before committing or pushing to remotes. + ### Installation ```bash diff --git a/prompts/generate-spec.md b/prompts/generate-spec.md index 3418e76..de1302a 100644 --- a/prompts/generate-spec.md +++ b/prompts/generate-spec.md @@ -217,6 +217,15 @@ If no specific standards are identified, state "Follow established repository pa [Focus on implementation constraints and HOW it will be built. Mention technical constraints, dependencies, or architectural decisions. If no technical constraints, state "No specific technical constraints identified."] +## Security Considerations + +[Identify security requirements and sensitive data handling needs. Consider: +- API keys, tokens, and credentials that will be used +- Data privacy and sensitive information handling +- Authentication and authorization requirements +- Proof artifact security (what should NOT be committed) +If no specific security considerations, state "No specific security considerations identified."] + ## Success Metrics [How will success be measured? Include specific metrics where possible.] diff --git a/prompts/generate-task-list-from-spec.md b/prompts/generate-task-list-from-spec.md index 0d3f89d..5a2b3e0 100644 --- a/prompts/generate-task-list-from-spec.md +++ b/prompts/generate-task-list-from-spec.md @@ -83,6 +83,8 @@ Proof artifacts provide evidence of task completion and are essential for the up - **Enable validation** (provide evidence for `/validate-spec-implementation`) - **Support troubleshooting** (logs, error messages, configuration states) +**Security Note**: When planning proof artifacts, remember that they will be committed to the repository. Artifacts should use placeholder values for API keys, tokens, and other sensitive data rather than real credentials. + ## Chain-of-Thought Analysis Process Before generating any tasks, you must follow this reasoning process: diff --git a/prompts/manage-tasks.md b/prompts/manage-tasks.md index c357c4a..248ecc1 100644 --- a/prompts/manage-tasks.md +++ b/prompts/manage-tasks.md @@ -199,6 +199,15 @@ Each parent task must include artifacts that: - **Enable validation** (provide evidence for `/validate-spec-implementation`) - **Support troubleshooting** (logs, error messages, configuration states) +### Security Warning + +**CRITICAL**: Proof artifacts will be committed to the repository. Never include sensitive data: + +- Replace API keys, tokens, and secrets with placeholders like `[YOUR_API_KEY_HERE]` or `[REDACTED]` +- Sanitize configuration examples to remove credentials +- Use example or dummy values instead of real production data +- Review all proof artifact files before committing to ensure no sensitive information is present + ### Proof Artifact Creation Protocol ```markdown @@ -217,10 +226,12 @@ For each parent task completion: - ## Demo Validation section showing criteria met [ ] **Format with Markdown**: Use code blocks, headers, and clear organization [ ] **Verify File Content**: Ensure the markdown file contains all required evidence +[ ] **Security Check**: Scan proof file for API keys, tokens, passwords, or other sensitive data and replace with placeholders **SIMPLE VERIFICATION**: One file per task, all evidence included **CONTENT VERIFICATION**: Check the markdown file contains required sections **DEMO VERIFICATION**: Ensure file demonstrates all demo criteria are met +**SECURITY VERIFICATION**: Confirm no real credentials or sensitive data are present **The single markdown proof file must be created BEFORE the parent task commit** ``` diff --git a/prompts/validate-spec-implementation.md b/prompts/validate-spec-implementation.md index ad7f5fb..b75f6a2 100644 --- a/prompts/validate-spec-implementation.md +++ b/prompts/validate-spec-implementation.md @@ -75,6 +75,7 @@ If no spec is provided, follow this exact sequence: - **GATE C:** All Proof Artifacts are accessible and functional → **REQUIRED**. - **GATE D:** All changed files are either in "Relevant Files" list OR explicitly justified in git commit messages → **REQUIRED**. - **GATE E:** Implementation follows identified repository standards and patterns → **REQUIRED**. +- **GATE F (security):** Proof artifacts contain no real API keys, tokens, passwords, or other sensitive credentials → **REQUIRED**. ## Evaluation Rubric (score each 0–3 to guide severity) @@ -138,6 +139,7 @@ For each Functional Requirement, Demoable Unit, and Repository Standard: - CLI commands execute successfully with expected output - Test references exist and can be executed - Screenshots/demos show required functionality + - **Security Check**: Proof artifacts contain no real API keys, tokens, passwords, or sensitive data 3) **Requirement Implementation** - Functional requirements are present in changed code @@ -164,6 +166,7 @@ For each Functional Requirement, Demoable Unit, and Repository Standard: - Any `Unknown` entries in the Coverage Matrix - Repository pattern violations (coding standards, quality gates, workflows) - Implementation that ignores identified repository conventions +- **Real API keys, tokens, passwords, or credentials in proof artifacts** (auto CRITICAL) ## Output (single human-readable Markdown report)