.kiro/docs/security-guide.md
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.
Principle: Always review agent-generated code, especially for security-critical components.
Why: Agents can make mistakes, miss edge cases, or introduce vulnerabilities unintentionally.
Practice:
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:
allowedTools to restrict agent capabilitiestoolsSettings.allowedPaths to restrict file accessPrinciple: Use multiple layers of security controls.
Why: No single control is perfect; layered defenses catch what others miss.
Practice:
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:
Risk: May suggest insecure architectures or skip security requirements.
Mitigation:
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
Risk: May introduce vulnerabilities like SQL injection, XSS, or insecure deserialization.
Mitigation:
Common Vulnerabilities to Watch:
Risk: May miss subtle vulnerabilities or provide false confidence.
Mitigation:
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
Risk: May accidentally remove security checks during refactoring.
Mitigation:
Purpose: Catch security issues before they reach the repository.
Configuration:
{
"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.
Purpose: Prevent accidental logging of sensitive data.
Configuration:
{
"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.
Purpose: Prevent accidental modification of critical documentation.
Configuration:
{
"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."
}
}
Purpose: Inject security rules into every conversation.
Key Rules to Include:
---
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
TypeScript/JavaScript:
- 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:
- 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:
- 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 servers extend agent capabilities but introduce security risks:
1. Review Server Permissions
Before installing an MCP server, review what it can do:
# 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:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
3. Limit Server Scope
Use least privilege for API tokens:
4. Review Server Code
For open-source MCP servers:
# 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:
{
"mcpServers": {
"github": {
"autoApprove": ["search_repositories", "get_file_contents"]
}
}
}
Never auto-approve:
Risk: Secrets in version control can be extracted from history.
Prevention:
# 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
Good:
# .env file (not committed)
DATABASE_URL=postgresql://user:pass@localhost/db
API_KEY=sk-...
# Load in application
export $(cat .env | xargs)
Bad:
// Hardcoded secret (never do this!)
const apiKey = "sk-1234567890abcdef";
For production:
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.