everything-claude-code/.kiro/docs/security-guide.md

# Security Guide for Agentic Workflows

## Introduction

AI agents are powerful development tools, but they introduce unique security considerations. This guide covers security best practices for using agentic workflows safely and responsibly.

## Core Security Principles

### 1. Trust but Verify

**Principle**: Always review agent-generated code, especially for security-critical components.

**Why**: Agents can make mistakes, miss edge cases, or introduce vulnerabilities unintentionally.

**Practice**:
- Review all authentication and authorization code manually
- Verify cryptographic implementations against standards
- Check input validation and sanitization
- Test error handling for information leakage

### 2. Least Privilege

**Principle**: Grant agents only the tools and access they need for their specific role.

**Why**: Limiting agent capabilities reduces the blast radius of potential mistakes.

**Practice**:
- Use `allowedTools` to restrict agent capabilities
- Read-only agents (planner, architect) should not have write access
- Review agents should not have shell access
- Use `toolsSettings.allowedPaths` to restrict file access

### 3. Defense in Depth

**Principle**: Use multiple layers of security controls.

**Why**: No single control is perfect; layered defenses catch what others miss.

**Practice**:
- Enable security-focused hooks (git-push-review, doc-file-warning)
- Use the security-reviewer agent before merging
- Maintain security steering files for consistent rules
- Run automated security scans in CI/CD

### 4. Secure by Default

**Principle**: Security should be the default, not an afterthought.

**Why**: It's easier to maintain security from the start than to retrofit it later.

**Practice**:
- Enable auto-inclusion security steering files
- Use TDD workflow with security test cases
- Include security requirements in planning phase
- Document security decisions in lessons-learned

## Agent-Specific Security

### Planner Agent

**Risk**: May suggest insecure architectures or skip security requirements.

**Mitigation**:
- Always include security requirements in planning prompts
- Review plans with security-reviewer agent
- Use security-review skill during planning
- Document security constraints in requirements

**Example Secure Prompt**:
```
Plan a user authentication feature with these security requirements:
- Password hashing with bcrypt (cost factor 12)
- Rate limiting (5 attempts per minute)
- JWT tokens with 15-minute expiry
- Refresh tokens in httpOnly cookies
- CSRF protection for state-changing operations
```

### Code-Writing Agents (TDD Guide, Build Error Resolver)

**Risk**: May introduce vulnerabilities like SQL injection, XSS, or insecure deserialization.

**Mitigation**:
- Enable security steering files (auto-loaded)
- Use git-push-review hook to catch issues before commit
- Run security-reviewer agent after implementation
- Include security test cases in TDD workflow

**Common Vulnerabilities to Watch**:
- SQL injection (use parameterized queries)
- XSS (sanitize user input, escape output)
- CSRF (use tokens for state-changing operations)
- Path traversal (validate and sanitize file paths)
- Command injection (avoid shell execution with user input)
- Insecure deserialization (validate before deserializing)

### Security Reviewer Agent

**Risk**: May miss subtle vulnerabilities or provide false confidence.

**Mitigation**:
- Use as one layer, not the only layer
- Combine with automated security scanners
- Review findings manually
- Update security steering files with new patterns

**Best Practice**:
```
1. Run security-reviewer agent
2. Run automated scanner (Snyk, SonarQube, etc.)
3. Manual review of critical components
4. Document findings in lessons-learned
```

### Refactor Cleaner Agent

**Risk**: May accidentally remove security checks during refactoring.

**Mitigation**:
- Use verification-loop skill to validate behavior preservation
- Include security tests in test suite
- Review diffs carefully for removed security code
- Run security-reviewer after refactoring

## Hook Security

### Git Push Review Hook

**Purpose**: Catch security issues before they reach the repository.

**Configuration**:
```json
{
  "name": "git-push-review",
  "version": "1.0.0",
  "description": "Review code before git push",
  "enabled": true,
  "when": {
    "type": "preToolUse",
    "toolTypes": ["shell"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Review the code for security issues before pushing. Check for: SQL injection, XSS, CSRF, authentication bypasses, information leakage, and insecure cryptography. Block the push if critical issues are found."
  }
}
```

**Best Practice**: Keep this hook enabled always, especially for production branches.

### Console Log Check Hook

**Purpose**: Prevent accidental logging of sensitive data.

**Configuration**:
```json
{
  "name": "console-log-check",
  "version": "1.0.0",
  "description": "Check for console.log statements",
  "enabled": true,
  "when": {
    "type": "fileEdited",
    "patterns": ["*.js", "*.ts", "*.tsx"]
  },
  "then": {
    "type": "runCommand",
    "command": "grep -n 'console\\.log' \"$KIRO_FILE_PATH\" && echo 'Warning: console.log found' || true"
  }
}
```

**Why**: Console logs can leak sensitive data (passwords, tokens, PII) in production.

### Doc File Warning Hook

**Purpose**: Prevent accidental modification of critical documentation.

**Configuration**:
```json
{
  "name": "doc-file-warning",
  "version": "1.0.0",
  "description": "Warn before modifying documentation files",
  "enabled": true,
  "when": {
    "type": "preToolUse",
    "toolTypes": ["write"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "If you're about to modify a README, SECURITY, or LICENSE file, confirm this is intentional and the changes are appropriate."
  }
}
```

## Steering File Security

### Security Steering File

**Purpose**: Inject security rules into every conversation.

**Key Rules to Include**:
```markdown
---
inclusion: auto
description: Security best practices and vulnerability prevention
---

# Security Rules

## Input Validation
- Validate all user input on the server side
- Use allowlists, not denylists
- Sanitize input before use
- Reject invalid input, don't try to fix it

## Authentication
- Use bcrypt/argon2 for password hashing (never MD5/SHA1)
- Implement rate limiting on authentication endpoints
- Use secure session management (httpOnly, secure, sameSite cookies)
- Implement account lockout after failed attempts

## Authorization
- Check authorization on every request
- Use principle of least privilege
- Implement role-based access control (RBAC)
- Never trust client-side authorization checks

## Cryptography
- Use TLS 1.3 for transport security
- Use established libraries (don't roll your own crypto)
- Use secure random number generators
- Rotate keys regularly

## Data Protection
- Encrypt sensitive data at rest
- Never log passwords, tokens, or PII
- Use parameterized queries (prevent SQL injection)
- Sanitize output (prevent XSS)

## Error Handling
- Never expose stack traces to users
- Log errors securely with correlation IDs
- Use generic error messages for users
- Implement proper exception handling
```

### Language-Specific Security

**TypeScript/JavaScript**:
```markdown
- Use Content Security Policy (CSP) headers
- Sanitize HTML with DOMPurify
- Use helmet.js for Express security headers
- Validate with Zod/Yup, not manual checks
- Use prepared statements for database queries
```

**Python**:
```markdown
- Use parameterized queries with SQLAlchemy
- Sanitize HTML with bleach
- Use secrets module for random tokens
- Validate with Pydantic
- Use Flask-Talisman for security headers
```

**Go**:
```markdown
- Use html/template for HTML escaping
- Use crypto/rand for random generation
- Use prepared statements with database/sql
- Validate with validator package
- Use secure middleware for HTTP headers
```

## MCP Server Security

### Risk Assessment

MCP servers extend agent capabilities but introduce security risks:

- **Network Access**: Servers can make external API calls
- **File System Access**: Some servers can read/write files
- **Credential Storage**: Servers may require API keys
- **Code Execution**: Some servers can execute arbitrary code

### Secure MCP Configuration

**1. Review Server Permissions**

Before installing an MCP server, review what it can do:
```bash
# Check server documentation
# Understand what APIs it calls
# Review what data it accesses
```

**2. Use Environment Variables for Secrets**

Never hardcode API keys in `mcp.json`:
```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
```

**3. Limit Server Scope**

Use least privilege for API tokens:
- GitHub: Use fine-grained tokens with minimal scopes
- Cloud providers: Use service accounts with minimal permissions
- Databases: Use read-only credentials when possible

**4. Review Server Code**

For open-source MCP servers:
```bash
# Clone and review the source
git clone https://github.com/org/mcp-server
cd mcp-server
# Review for security issues
grep -r "eval\|exec\|shell" .
```

**5. Use Auto-Approve Carefully**

Only auto-approve tools you fully trust:
```json
{
  "mcpServers": {
    "github": {
      "autoApprove": ["search_repositories", "get_file_contents"]
    }
  }
}
```

Never auto-approve:
- File write operations
- Shell command execution
- Database modifications
- API calls that change state

## Secrets Management

### Never Commit Secrets

**Risk**: Secrets in version control can be extracted from history.

**Prevention**:
```bash
# Add to .gitignore
echo ".env" >> .gitignore
echo ".kiro/settings/mcp.json" >> .gitignore
echo "secrets/" >> .gitignore

# Use git-secrets or similar tools
git secrets --install
git secrets --register-aws
```

### Use Environment Variables

**Good**:
```bash
# .env file (not committed)
DATABASE_URL=postgresql://user:pass@localhost/db
API_KEY=sk-...

# Load in application
export $(cat .env | xargs)
```

**Bad**:
```javascript
// Hardcoded secret (never do this!)
const apiKey = "sk-1234567890abcdef";
```

### Rotate Secrets Regularly

- API keys: Every 90 days
- Database passwords: Every 90 days
- JWT signing keys: Every 30 days
- Refresh tokens: On suspicious activity

### Use Secret Management Services

For production:
- AWS Secrets Manager
- HashiCorp Vault
- Azure Key Vault
- Google Secret Manager

## Incident Response

### If an Agent Generates Vulnerable Code

1. **Stop**: Don't merge or deploy the code
2. **Analyze**: Understand the vulnerability
3. **Fix**: Correct the issue manually or with security-reviewer agent
4. **Test**: Verify the fix with security tests
5. **Document**: Add pattern to lessons-learned.md
6. **Update**: Improve security steering files to prevent recurrence

### If Secrets Are Exposed

1. **Revoke**: Immediately revoke exposed credentials
2. **Rotate**: Generate new credentials
3. **Audit**: Check for unauthorized access
4. **Clean**: Remove secrets from git history (git-filter-repo)
5. **Prevent**: Update .gitignore and pre-commit hooks

### If a Security Issue Reaches Production

1. **Assess**: Determine severity and impact
2. **Contain**: Deploy hotfix or take system offline
3. **Notify**: Inform affected users if required
4. **Investigate**: Determine root cause
5. **Remediate**: Fix the issue permanently
6. **Learn**: Update processes to prevent recurrence

## Security Checklist

### Before Starting Development

- [ ] Security steering files enabled (auto-inclusion)
- [ ] Security-focused hooks enabled (git-push-review, console-log-check)
- [ ] MCP servers reviewed and configured securely
- [ ] Secrets management strategy in place
- [ ] .gitignore includes sensitive files

### During Development

- [ ] Security requirements included in planning
- [ ] TDD workflow includes security test cases
- [ ] Input validation on all user input
- [ ] Output sanitization for all user-facing content
- [ ] Authentication and authorization implemented correctly
- [ ] Cryptography uses established libraries
- [ ] Error handling doesn't leak information

### Before Merging

- [ ] Code reviewed by security-reviewer agent
- [ ] Automated security scanner run (Snyk, SonarQube)
- [ ] Manual review of security-critical code
- [ ] No secrets in code or configuration
- [ ] No console.log statements with sensitive data
- [ ] Security tests passing

### Before Deploying

- [ ] Security headers configured (CSP, HSTS, etc.)
- [ ] TLS/HTTPS enabled
- [ ] Rate limiting configured
- [ ] Monitoring and alerting set up
- [ ] Incident response plan documented
- [ ] Secrets rotated if needed

## Resources

### Tools

- **Static Analysis**: SonarQube, Semgrep, CodeQL
- **Dependency Scanning**: Snyk, Dependabot, npm audit
- **Secret Scanning**: git-secrets, truffleHog, GitGuardian
- **Runtime Protection**: OWASP ZAP, Burp Suite

### Standards

- **OWASP Top 10**: https://owasp.org/www-project-top-ten/
- **CWE Top 25**: https://cwe.mitre.org/top25/
- **NIST Guidelines**: https://www.nist.gov/cybersecurity

### Learning

- **OWASP Cheat Sheets**: https://cheatsheetseries.owasp.org/
- **PortSwigger Web Security Academy**: https://portswigger.net/web-security
- **Secure Code Warrior**: https://www.securecodewarrior.com/

## Conclusion

Security in agentic workflows requires vigilance and layered defenses. By following these best practices—reviewing agent output, using security-focused agents and hooks, maintaining security steering files, and securing MCP servers—you can leverage the power of AI agents while maintaining strong security posture.

Remember: agents are tools that amplify your capabilities, but security remains your responsibility. Trust but verify, use defense in depth, and always prioritize security in your development workflow.