|
| 1 | +# Security Guidelines |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This document describes the security practices and tools used in the OUDS Flutter SDK project to maintain the highest standards of code quality and security. |
| 6 | + |
| 7 | +## Automated Security Scanning |
| 8 | + |
| 9 | +### Continuous Integration Security Checks |
| 10 | + |
| 11 | +Every commit and pull request triggers automated security scans: |
| 12 | + |
| 13 | +#### 1. **SAST - Semgrep Security Analysis** |
| 14 | +- **When**: Every push and pull request |
| 15 | +- **What**: Scans Dart/Flutter code for security vulnerabilities |
| 16 | +- **Rules**: Security audit, OWASP Top 10, Dart-specific patterns |
| 17 | +- **Excludes**: Generated files (`*.g.dart`, `*.freezed.dart`), build artifacts, tests |
| 18 | +- **Output**: SARIF format in GitHub Security tab |
| 19 | + |
| 20 | +#### 2. **Dart Static Analysis** |
| 21 | +- **When**: Every push and pull request |
| 22 | +- **Flags**: `--fatal-infos --fatal-warnings` |
| 23 | +- **Scope**: All packages in workspace |
| 24 | +- **Purpose**: Enforce language best practices |
| 25 | + |
| 26 | +#### 3. **Flutter Analysis** |
| 27 | +- **When**: Every push and pull request |
| 28 | +- **Purpose**: Flutter framework-specific checks |
| 29 | +- **Scope**: All Flutter packages |
| 30 | + |
| 31 | +#### 4. **Secret Scanning - Gitleaks** |
| 32 | +- **When**: Every push |
| 33 | +- **What**: Scans for hardcoded secrets |
| 34 | +- **Detects**: API keys, credentials, certificates, tokens |
| 35 | +- **Config**: `.gitleaks.toml` |
| 36 | + |
| 37 | +### Scheduled Security Scans |
| 38 | + |
| 39 | +- **Frequency**: Weekly (every Monday at 1:00 UTC) |
| 40 | +- **Tools**: Semgrep, Dart Analysis, Gitleaks |
| 41 | +- **Purpose**: Continuous monitoring and compliance |
| 42 | + |
| 43 | +--- |
| 44 | + |
| 45 | +## Code Review Process |
| 46 | + |
| 47 | +### Branch Protection Rules |
| 48 | + |
| 49 | +The `main` and `develop` branches are protected: |
| 50 | + |
| 51 | +1. ✅ Require pull request reviews (minimum 1) |
| 52 | +2. ✅ Require status checks to pass: |
| 53 | + - SAST Analysis (Semgrep) |
| 54 | + - Dart Analysis |
| 55 | + - Flutter Analyze |
| 56 | + - Build tests |
| 57 | +3. ✅ Require branches to be up to date |
| 58 | +4. ✅ Code owners review required |
| 59 | + |
| 60 | +### Pull Request Workflow |
| 61 | + |
| 62 | +``` |
| 63 | +1. Create feature branch from develop |
| 64 | + ↓ |
| 65 | +2. Make changes and push |
| 66 | + ↓ |
| 67 | +3. Automated checks run: |
| 68 | + - SAST Analysis |
| 69 | + - Tests |
| 70 | + - Code quality checks |
| 71 | + ↓ |
| 72 | +4. Request manual review |
| 73 | + ↓ |
| 74 | +5. Address feedback |
| 75 | + ↓ |
| 76 | +6. Approval received |
| 77 | + ↓ |
| 78 | +7. Merge to develop (or main for hotfixes) |
| 79 | +``` |
| 80 | + |
| 81 | +--- |
| 82 | + |
| 83 | +## Dependency Security |
| 84 | + |
| 85 | +### Managing Dart Packages |
| 86 | + |
| 87 | +- **Source**: pub.dev only |
| 88 | +- **Versioning**: Use exact or pinned version ranges |
| 89 | +- **Updates**: Reviewed before merging |
| 90 | +- **Advisories**: Security advisories checked daily |
| 91 | + |
| 92 | +### Dependabot Integration |
| 93 | + |
| 94 | +- **Frequency**: Weekly checks |
| 95 | +- **Scope**: pubspec.yaml, pubspec.lock |
| 96 | +- **Actions**: |
| 97 | + - Creates pull requests for updates |
| 98 | + - Security patches auto-merged (if tests pass) |
| 99 | + - Major updates require manual review |
| 100 | + |
| 101 | +### Flutter SDK |
| 102 | + |
| 103 | +- **Channel**: Stable (no beta/dev) |
| 104 | +- **Updates**: Regular patch updates |
| 105 | +- **Testing**: All tests run on each update |
| 106 | +- **Pinning**: Version specified in GitHub Actions workflows |
| 107 | + |
| 108 | +--- |
| 109 | + |
| 110 | +## Secure Development Practices |
| 111 | + |
| 112 | +### Code Quality |
| 113 | + |
| 114 | +1. **Static Analysis**: Mandatory passing checks |
| 115 | +2. **Type Safety**: Strong typing enforced |
| 116 | +3. **Null Safety**: Dart null safety enabled |
| 117 | +4. **Documentation**: Security concerns documented |
| 118 | + |
| 119 | +### Testing |
| 120 | + |
| 121 | +- Unit tests for all features |
| 122 | +- Integration tests for critical paths |
| 123 | +- No hardcoded secrets in tests |
| 124 | +- Mock external APIs (no real credentials) |
| 125 | + |
| 126 | +### Documentation |
| 127 | + |
| 128 | +- Inline comments for security-critical code |
| 129 | +- README.md for general information |
| 130 | +- SECURITY.md for vulnerability reporting |
| 131 | +- CONTRIBUTING.md for development guidelines |
| 132 | + |
| 133 | +--- |
| 134 | + |
| 135 | +## Permissions & Access Control |
| 136 | + |
| 137 | +### GitHub Actions Permissions |
| 138 | + |
| 139 | +All workflows use **least privilege** permissions: |
| 140 | + |
| 141 | +```yaml |
| 142 | +permissions: |
| 143 | + contents: read # Read-only |
| 144 | + security-events: write # Write SAST results only |
| 145 | + actions: read # Read workflow metadata |
| 146 | +``` |
| 147 | +
|
| 148 | +### Secrets Management |
| 149 | +
|
| 150 | +- Use GitHub Secrets for sensitive data |
| 151 | +- Secrets masked in logs automatically |
| 152 | +- GitHub tokens rotated regularly |
| 153 | +- Never hardcode secrets in code or configs |
| 154 | +
|
| 155 | +### Branch Protection |
| 156 | +
|
| 157 | +- Only admins can push to `main` |
| 158 | +- Force-push disabled on protected branches |
| 159 | +- Deletion of protected branches disabled |
| 160 | + |
| 161 | +--- |
| 162 | + |
| 163 | +## Version Control Security |
| 164 | + |
| 165 | +### Commit History |
| 166 | + |
| 167 | +- All commits tracked in version control |
| 168 | +- No commit rewriting on main branches |
| 169 | +- Audit trail for all changes |
| 170 | + |
| 171 | +### Tag Management |
| 172 | + |
| 173 | +- Release tags on `main` branch only |
| 174 | +- Tag naming: `MAJOR.MINOR.PATCH` (semver) |
| 175 | +- Future: GPG-signed releases |
| 176 | + |
| 177 | +--- |
| 178 | + |
| 179 | +## Incident Response |
| 180 | + |
| 181 | +### Security Vulnerability Process |
| 182 | + |
| 183 | +``` |
| 184 | +Report |
| 185 | + ↓ |
| 186 | +Acknowledge (48 hours) |
| 187 | + ↓ |
| 188 | +Investigate & Reproduce |
| 189 | + ↓ |
| 190 | +Develop Fix (private branch) |
| 191 | + ↓ |
| 192 | +Review & Test |
| 193 | + ↓ |
| 194 | +Release Patch Version |
| 195 | + ↓ |
| 196 | +Publish Security Advisory |
| 197 | + ↓ |
| 198 | +30-day public disclosure |
| 199 | +``` |
| 200 | +
|
| 201 | +### Embargo Period |
| 202 | +
|
| 203 | +- **Default**: 90 days coordinated disclosure |
| 204 | +- **Early Notification**: Available for major users |
| 205 | +- **Public Release**: 30 days after patch availability |
| 206 | +
|
| 207 | +### Contacts |
| 208 | +
|
| 209 | +- **Primary**: [opensource.contact@orange.com](mailto:opensource.contact@orange.com) |
| 210 | +- **CERT**: [cert.cc@orange.com](mailto:cert.cc@orange.com) |
| 211 | +- **Maintainers**: See [MAINTAINERS.md](./MAINTAINERS.md) |
| 212 | +
|
| 213 | +--- |
| 214 | +
|
| 215 | +## Compliance Standards |
| 216 | +
|
| 217 | +### OWASP Top 10 (2021) |
| 218 | +
|
| 219 | +The project follows OWASP guidelines: |
| 220 | +
|
| 221 | +- ✅ A01: Broken Access Control |
| 222 | +- ✅ A02: Cryptographic Failures |
| 223 | +- ✅ A03: Injection |
| 224 | +- ✅ A04: Insecure Design |
| 225 | +- ✅ A05: Security Misconfiguration |
| 226 | +- ✅ A06: Vulnerable Components |
| 227 | +- ✅ A07: Authentication Failures |
| 228 | +- ✅ A08: Data Integrity Failures |
| 229 | +- ✅ A09: Logging/Monitoring Failures |
| 230 | +- ✅ A10: SSRF |
| 231 | +
|
| 232 | +### OpenSSF Best Practices |
| 233 | +
|
| 234 | +The project aims for compliance with: |
| 235 | +- SAST analysis enabled ✅ |
| 236 | +- Dependency scanning enabled ✅ |
| 237 | +- Branch protection configured ✅ |
| 238 | +- Version control used ✅ |
| 239 | +- Security policy published ✅ |
| 240 | +
|
| 241 | +### License Compliance |
| 242 | +
|
| 243 | +- SPDX headers on all source files |
| 244 | +- NOTICE.txt for third-party attribution |
| 245 | +- Regular license audits |
| 246 | +- MIT License compliance verified |
| 247 | +
|
| 248 | +--- |
| 249 | +
|
| 250 | +## Security Tools Configuration |
| 251 | +
|
| 252 | +### Workflow: `.github/workflows/codeql.yml` |
| 253 | +
|
| 254 | +Runs Dart/Flutter security analysis on: |
| 255 | +- Every push to `main` and `develop` |
| 256 | +- Every pull request to `main` and `develop` |
| 257 | +- Weekly schedule (Monday 1:00 UTC) |
| 258 | +- Manual trigger via workflow_dispatch |
| 259 | +
|
| 260 | +**Configuration**: |
| 261 | +```yaml |
| 262 | +- Dart Analysis: --fatal-infos --fatal-warnings |
| 263 | +- Flutter Analyze: --no-pub |
| 264 | +- Semgrep Rules: security-audit, owasp-top-ten, dart |
| 265 | +- Timeout: 60 minutes |
| 266 | +- SARIF Upload: Enabled |
| 267 | +``` |
| 268 | + |
| 269 | +### Dependency Scanning: `.github/dependabot.yml` |
| 270 | + |
| 271 | +Monitors and updates: |
| 272 | +- Dart packages (pubspec.yaml) |
| 273 | +- GitHub Actions versions |
| 274 | +- Frequency: Weekly |
| 275 | + |
| 276 | +### Secret Scanning: `.gitleaks.toml` |
| 277 | + |
| 278 | +Prevents hardcoded secrets: |
| 279 | +- API keys |
| 280 | +- Database credentials |
| 281 | +- OAuth tokens |
| 282 | +- Private certificates |
| 283 | +- SSH keys |
| 284 | + |
| 285 | +--- |
| 286 | + |
| 287 | +## Best Practices Checklist |
| 288 | + |
| 289 | +- ✅ SAST enabled on all branches |
| 290 | +- ✅ Secret scanning enabled |
| 291 | +- ✅ Dependency updates automated |
| 292 | +- ✅ Code review required |
| 293 | +- ✅ Branch protection configured |
| 294 | +- ✅ Version pinning (SHA-256) |
| 295 | +- ✅ Least privilege permissions |
| 296 | +- ✅ Audit logging enabled |
| 297 | +- ✅ Security policy published |
| 298 | +- ✅ Incident response plan |
| 299 | +- ✅ OWASP compliance |
| 300 | +- ✅ License compliance |
| 301 | + |
| 302 | +--- |
| 303 | + |
| 304 | +## Resources |
| 305 | + |
| 306 | +- [OWASP Top 10](https://owasp.org/Top10/) |
| 307 | +- [OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/) |
| 308 | +- [Dart Security](https://dart.dev/guides/security) |
| 309 | +- [Flutter Security](https://flutter.dev/docs/testing/security-testing) |
| 310 | +- [GitHub Security](https://github.com/security) |
| 311 | + |
| 312 | +--- |
| 313 | + |
| 314 | +**Last Updated**: 2026-04-17 |
| 315 | +**Maintained By**: OUDS Security Team |
| 316 | +**License**: MIT |
| 317 | + |
0 commit comments