diff --git a/CHANGELOG.md b/CHANGELOG.md index 7fcf2eb..551edcb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## Unreleased +- Added dedicated security posture documentation (`docs/security-posture.md`) with `/security-review` scope, false-positive handling, and CI integration guidance. - Added a "Value in 5 minutes" demo section to `README.md` with one-prompt flow and three copy-ready scenarios. - Added visual demo artifact `assets/demo-5min-flow.svg` for quick onboarding value proof. diff --git a/README.md b/README.md index c0a537b..1996442 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,7 @@ Three ready-to-run scenarios: ## Included assets - **Release checklist**: `docs/official-release-checklist.md` for official/public release prep. +- **Security posture**: `docs/security-posture.md` for `/security-review` scope, false-positive handling, and CI integration. - **Agents** - `flutter-app-builder` (general Flutter implementation) - `flutter-code-reviewer` @@ -154,6 +155,7 @@ Three ready-to-run scenarios: 8. For security audit and secrets scanning use: - `security-review` - `docs/security-audit-checklist.md` + - `docs/security-posture.md` 9. Keep generated output aligned with plugin rules. 10. For dependency upgrades, also follow: - `docs/dependency-upgrade-checklist.md` diff --git a/docs/official-release-checklist.md b/docs/official-release-checklist.md index aacbd7c..e15fc8f 100644 --- a/docs/official-release-checklist.md +++ b/docs/official-release-checklist.md @@ -42,6 +42,7 @@ Use this checklist before tagging a public release. ## Security readiness - Security review flow is documented (`docs/security-audit-checklist.md`). +- Security posture page is documented (`docs/security-posture.md`). - `/security-review` command and security skill exist and are linked from README. - Official security references are included and up to date. - Optional GitHub Action template exists for PR security reviews (`templates/github_actions_security_review.yml`). diff --git a/docs/security-posture.md b/docs/security-posture.md new file mode 100644 index 0000000..d411080 --- /dev/null +++ b/docs/security-posture.md @@ -0,0 +1,56 @@ +# Security Posture + +This page defines what `/security-review` covers, how findings are reported, and how to wire checks into CI. + +## Scope of `/security-review` + +The command follows `skills/security-audit/SKILL.md` and `docs/security-audit-checklist.md`: + +1. Diff-aware review first (focus on pending changes). +2. Secrets scan and credential leak checks. +3. Code-level security checks for risky patterns. +4. Mobile hardening checks (Android/iOS release posture). +5. Supply-chain/dependency checks. +6. Findings prioritized by severity and exploitability. + +## Findings format + +Security findings should be returned in this structure: + +- Severity: `critical`, `high`, `medium`, `low`. +- Risk: what can be exploited and under which conditions. +- Evidence: affected file/path and short explanation. +- Remediation: concrete fix steps. +- Verification: command/check proving the fix. + +## False-positive handling + +Use these rules to keep output actionable: + +- Mark suspected false positives explicitly. +- Explain why the alert is likely non-exploitable. +- Keep a short "accepted risk" note only with clear rationale. +- Do not suppress high/critical issues without remediation plan. + +## CI integration + +Recommended baseline: + +1. Run `/review-flutter-code` on PRs for architecture + quality checks. +2. Run `/security-review` for security findings before merge/release. +3. Keep `validate-plugin`, `doc-link-health`, and `api-stability` workflows green. +4. Enforce release checklist completion in `docs/official-release-checklist.md`. + +Optional CI extension: + +- Use `templates/github_actions_security_review.yml` as a starter workflow. +- Add repository secrets only through your CI provider secret store. +- Block release tags if high/critical findings are unresolved. + +## References + +- Flutter security: https://docs.flutter.dev/security +- OWASP MASVS: https://mas.owasp.org/MASVS/ +- Google Play security best practices: https://developer.android.com/privacy-and-security/security-best-practices +- Apple security resources: https://developer.apple.com/security/ +- Claude Code Security Review: https://github.com/anthropics/claude-code-security-review