[plan] Document gosec security exclusions and rationale

[github-actions]

Objective

Document why specific gosec rules are excluded in .golangci.yml, providing security review rationale and creating an audit trail for compliance.

Context

Currently, .golangci.yml excludes several gosec rules:

• G101: Hardcoded credentials (false positives)
• G602: Slice bounds (runtime handled)
• G115: Integer overflow (acceptable)

Additionally, there are file-specific exceptions for docker/git commands.

While these exclusions are sensible, they lack documentation explaining:

• Why each rule is excluded
• What security risk is being accepted
• Who made the decision and when
• CWE mappings for compliance

This documentation is important for:

• Security audits
• Compliance requirements (SOC2, ISO 27001)
• Onboarding new team members
• Future security reviews

Files to Modify/Create

Option 1: Update existing documentation

• DEVGUIDE.md - Add security exclusions section

Option 2: Create dedicated security documentation

• SECURITY.md - Security practices and policies (if not exists)
• Or add section to existing SECURITY.md

Implementation

Add a section documenting:

1. Global Exclusions

For each excluded rule, document:

• Rule ID (e.g., G101)
• Rule Name (e.g., "Hardcoded credentials")
• CWE Mapping (e.g., CWE-798)
• Exclusion Rationale: Why it's safe to exclude
• False Positive Examples: Specific cases causing issues
• Mitigation: How the actual risk is addressed
• Review Date: When exclusion was last reviewed

2. File-Specific Exclusions

Document exceptions in:

• pkg/workflow/docker.go
• pkg/workflow/git.go

Explain why these files need special treatment.

3. Suppression Annotations

Document the use of #nosec annotations:

• When to use them
• Required justification format
• Review process
• Examples

Suggested Structure

## Security Scanning Exclusions

### Overview

This project uses gosec for security scanning with specific exclusions documented below.

### Global Exclusions

#### G101: Hardcoded Credentials
- **CWE**: CWE-798 (Use of Hard-coded Credentials)
- **Rationale**: High false positive rate on variable names like `tokenURL`, `secretName`
- **Mitigation**: Actual secrets stored in GitHub Secrets, never committed
- **Review**: 2025-12-25

#### G602: Slice Bounds Check
- **CWE**: CWE-119 (Improper Restriction of Operations within Memory Buffer)
- **Rationale**: Go runtime provides bounds checking; panics are acceptable
- **Mitigation**: Unit tests cover edge cases
- **Review**: 2025-12-25

[Continue for all exclusions...]

### File-Specific Exclusions

#### Docker Command Execution
- **Files**: `pkg/workflow/docker.go`
- **Rules**: G204 (Subprocess with variable)
- **Rationale**: Docker commands constructed from validated workflow config
- **Mitigation**: Input validation, allowlist checks
- **Review**: 2025-12-25

[Continue for all files...]

### Suppression Guidelines

Use `#nosec` annotations with justification:

```go
// #nosec G204 -- Command arguments validated via allowlist
cmd := exec.Command("docker", args...)

Required format:

• Include rule ID (G204)
• Use -- separator
• Provide brief justification
• Keep justification under 80 chars

## Acceptance Criteria

- [ ] Documentation includes all gosec exclusions
- [ ] Each exclusion has clear rationale
- [ ] CWE mappings provided where applicable
- [ ] File-specific exceptions documented
- [ ] Suppression guidelines included
- [ ] Examples provided for clarity
- [ ] Review dates documented
- [ ] Documentation location chosen (DEVGUIDE.md vs SECURITY.md)

## Research Required

1. Review `.golangci.yml` for all gosec exclusions
2. Check gosec documentation for CWE mappings: https://github.com/securego/gosec/blob/master/issue/issue.go
3. Review files with specific exclusions (docker.go, git.go)
4. Identify existing `#nosec` annotations in codebase

## Time Estimate

1-2 hours

## Benefits

- ✅ Better security audit trail
- ✅ Easier compliance reporting
- ✅ Onboarding documentation
- ✅ Future security review reference
- ✅ Team decision transparency
Related to #7612




> AI generated by [Plan Command](https://github.com/githubnext/gh-aw/actions/runs/20503952744) for discussion #7599

<!-- agentic-workflow: Plan Command, engine: copilot, run: https://github.com/githubnext/gh-aw/actions/runs/20503952744 -->