Add Kiro base structure, install script, and docs (#809)

Co-authored-by: Sungmin Hong <hsungmin@amazon.com>
2026-04-05 08:43:29 +08:00 · 2026-03-22 21:55:40 -07:00
parent a411da9122
commit 2c23ff54d1
6 changed files with 1953 additions and 0 deletions
--- a/.kiro/docs/security-guide.md
+++ b/.kiro/docs/security-guide.md
@@ -0,0 +1,496 @@
+# 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.