@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/flask/rules/security.md

@@ -0,0 +1,267 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Flask Security Patterns
+
+## Password Hashing
+
+```python
+from werkzeug.security import generate_password_hash, check_password_hash
+
+class User(db.Model):
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(unique=True)
+    password_hash: Mapped[str]
+
+    def set_password(self, password: str):
+        self.password_hash = generate_password_hash(password)
+
+    def check_password(self, password: str) -> bool:
+        return check_password_hash(self.password_hash, password)
+
+# Usage
+user = User(email="test@example.com")
+user.set_password("secure_password")
+
+if user.check_password("secure_password"):
+    print("Password correct")
+```
+
+## CSRF Protection
+
+```python
+from flask_wtf.csrf import CSRFProtect
+
+csrf = CSRFProtect()
+csrf.init_app(app)
+
+# In templates
+<form method="post">
+    {{ csrf_token() }}
+    <!-- or -->
+    <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
+</form>
+
+# For AJAX requests
+<script>
+    fetch('/api/endpoint', {
+        method: 'POST',
+        headers: {
+            'X-CSRFToken': '{{ csrf_token() }}'
+        },
+        body: JSON.stringify(data)
+    });
+</script>
+
+# Exempt API routes from CSRF
+@csrf.exempt
+@app.route("/api/webhook", methods=["POST"])
+def webhook():
+    ...
+
+# Or exempt entire blueprint
+csrf.exempt(api_bp)
+```
+
+## Security Headers
+
+```python
+from flask_talisman import Talisman
+
+# Basic security headers
+Talisman(app, force_https=True)
+
+# Custom configuration
+Talisman(
+    app,
+    force_https=True,
+    strict_transport_security=True,
+    strict_transport_security_max_age=31536000,
+    content_security_policy={
+        "default-src": "'self'",
+        "script-src": ["'self'", "cdn.example.com"],
+        "style-src": ["'self'", "'unsafe-inline'"],
+        "img-src": ["'self'", "data:", "*.example.com"],
+    },
+)
+
+# Manual headers
+@app.after_request
+def add_security_headers(response):
+    response.headers["X-Content-Type-Options"] = "nosniff"
+    response.headers["X-Frame-Options"] = "DENY"
+    response.headers["X-XSS-Protection"] = "1; mode=block"
+    return response
+```
+
+## Session Security
+
+```python
+# Configuration
+app.config.update(
+    SECRET_KEY=os.environ["SECRET_KEY"],
+    SESSION_COOKIE_SECURE=True,        # HTTPS only
+    SESSION_COOKIE_HTTPONLY=True,      # No JavaScript access
+    SESSION_COOKIE_SAMESITE="Lax",     # CSRF protection
+    PERMANENT_SESSION_LIFETIME=timedelta(hours=24),
+)
+
+# Server-side sessions with Redis
+from flask_session import Session
+
+app.config["SESSION_TYPE"] = "redis"
+app.config["SESSION_REDIS"] = redis.from_url(os.environ["REDIS_URL"])
+Session(app)
+```
+
+## Input Validation
+
+```python
+from markupsafe import escape
+from marshmallow import Schema, fields, validate
+
+# Always validate input
+class UserInputSchema(Schema):
+    name = fields.Str(required=True, validate=validate.Length(min=1, max=100))
+    email = fields.Email(required=True)
+    bio = fields.Str(validate=validate.Length(max=500))
+
+@users_bp.route("/", methods=["POST"])
+def create_user():
+    schema = UserInputSchema()
+    data = schema.load(request.get_json())  # Validates and sanitizes
+    user = UserService.create(data)
+    return jsonify(UserSchema().dump(user)), 201
+
+# Escape output for HTML
+@app.route("/search")
+def search():
+    query = request.args.get("q", "")
+    safe_query = escape(query)  # Prevents XSS
+    return render_template("search.html", query=safe_query)
+```
+
+## SQL Injection Prevention
+
+```python
+# GOOD - Use ORM or parameterized queries
+user = User.query.filter_by(email=email).first()
+
+# GOOD - Raw SQL with parameters
+result = db.session.execute(
+    text("SELECT * FROM users WHERE email = :email"),
+    {"email": email}
+)
+
+# BAD - String interpolation (SQL injection vulnerable!)
+result = db.session.execute(f"SELECT * FROM users WHERE email = '{email}'")
+```
+
+## API Key Authentication
+
+```python
+from functools import wraps
+
+def require_api_key(f):
+    @wraps(f)
+    def decorated(*args, **kwargs):
+        api_key = request.headers.get("X-API-Key")
+
+        if not api_key:
+            return jsonify({"error": "API key required"}), 401
+
+        # Constant-time comparison to prevent timing attacks
+        import hmac
+        valid_key = current_app.config["API_KEY"]
+        if not hmac.compare_digest(api_key, valid_key):
+            return jsonify({"error": "Invalid API key"}), 401
+
+        return f(*args, **kwargs)
+    return decorated
+
+@api_bp.route("/data")
+@require_api_key
+def get_data():
+    return jsonify({"data": "sensitive"})
+```
+
+## Rate Limiting
+
+```python
+from flask_limiter import Limiter
+from flask_limiter.util import get_remote_address
+
+limiter = Limiter(
+    key_func=get_remote_address,
+    default_limits=["200 per day", "50 per hour"],
+    storage_uri="redis://localhost:6379",
+)
+
+@auth_bp.route("/login", methods=["POST"])
+@limiter.limit("5 per minute")
+def login():
+    ...
+
+# Per-user rate limiting
+@limiter.limit("100 per hour", key_func=lambda: current_user.id)
+def user_endpoint():
+    ...
+```
+
+## Secure File Uploads
+
+```python
+from werkzeug.utils import secure_filename
+import os
+
+ALLOWED_EXTENSIONS = {"png", "jpg", "jpeg", "gif", "pdf"}
+MAX_CONTENT_LENGTH = 16 * 1024 * 1024  # 16MB
+
+app.config["MAX_CONTENT_LENGTH"] = MAX_CONTENT_LENGTH
+
+def allowed_file(filename: str) -> bool:
+    return "." in filename and \
+           filename.rsplit(".", 1)[1].lower() in ALLOWED_EXTENSIONS
+
+@files_bp.route("/upload", methods=["POST"])
+def upload_file():
+    if "file" not in request.files:
+        return jsonify({"error": "No file provided"}), 400
+
+    file = request.files["file"]
+
+    if file.filename == "":
+        return jsonify({"error": "No file selected"}), 400
+
+    if not allowed_file(file.filename):
+        return jsonify({"error": "File type not allowed"}), 400
+
+    # Secure the filename
+    filename = secure_filename(file.filename)
+
+    # Generate unique filename
+    unique_filename = f"{uuid.uuid4()}_{filename}"
+
+    # Save to secure location
+    file.save(os.path.join(app.config["UPLOAD_FOLDER"], unique_filename))
+
+    return jsonify({"filename": unique_filename}), 201
+```
+
+## Secrets Management
+
+```python
+import os
+
+# GOOD - Environment variables
+app.config["SECRET_KEY"] = os.environ["SECRET_KEY"]
+app.config["DATABASE_URL"] = os.environ["DATABASE_URL"]
+
+# GOOD - Secrets file (not in repo)
+# config/secrets.py (in .gitignore)
+
+# BAD - Hardcoded secrets
+app.config["SECRET_KEY"] = "hardcoded-secret"  # NEVER do this
+```

package/configs/flask/rules/testing.md

@@ -0,0 +1,284 @@
+---
+paths:
+  - "tests/**/*.py"
+  - "**/test_*.py"
+---
+
+# Flask Testing Patterns
+
+## Test Configuration
+
+```python
+# conftest.py
+import pytest
+from app import create_app, db
+
+@pytest.fixture(scope="session")
+def app():
+    """Create application for testing."""
+    app = create_app("testing")
+    return app
+
+@pytest.fixture
+def client(app):
+    """Create test client."""
+    return app.test_client()
+
+@pytest.fixture
+def runner(app):
+    """Create CLI test runner."""
+    return app.test_cli_runner()
+
+@pytest.fixture
+def db_session(app):
+    """Create database session for testing."""
+    with app.app_context():
+        db.create_all()
+        yield db.session
+        db.session.rollback()
+        db.drop_all()
+```
+
+## Testing Config
+
+```python
+# config.py
+class TestingConfig:
+    TESTING = True
+    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"
+    WTF_CSRF_ENABLED = False
+    SECRET_KEY = "test-secret-key"
+```
+
+## API Endpoint Tests
+
+```python
+class TestUsersAPI:
+    def test_create_user(self, client, db_session):
+        response = client.post("/api/v1/users", json={
+            "email": "test@example.com",
+            "password": "password123",
+            "name": "Test User",
+        })
+
+        assert response.status_code == 201
+        data = response.get_json()
+        assert data["email"] == "test@example.com"
+        assert "id" in data
+        assert "password" not in data
+
+    def test_create_user_duplicate_email(self, client, db_session):
+        # Create existing user
+        user = User(email="existing@example.com", name="Existing")
+        db_session.add(user)
+        db_session.commit()
+
+        response = client.post("/api/v1/users", json={
+            "email": "existing@example.com",
+            "password": "password123",
+            "name": "New User",
+        })
+
+        assert response.status_code == 409
+
+    def test_get_user_not_found(self, client):
+        response = client.get("/api/v1/users/99999")
+        assert response.status_code == 404
+
+    def test_list_users_pagination(self, client, db_session):
+        # Create users
+        for i in range(25):
+            db_session.add(User(email=f"user{i}@example.com", name=f"User {i}"))
+        db_session.commit()
+
+        response = client.get("/api/v1/users?page=2&size=10")
+
+        assert response.status_code == 200
+        data = response.get_json()
+        assert len(data["items"]) == 10
+        assert data["total"] == 25
+```
+
+## Authentication Tests
+
+```python
+@pytest.fixture
+def auth_headers(client, db_session):
+    """Create authenticated user and return headers."""
+    user = User(email="auth@example.com", name="Auth User")
+    user.set_password("password123")
+    db_session.add(user)
+    db_session.commit()
+
+    response = client.post("/api/v1/auth/login", json={
+        "email": "auth@example.com",
+        "password": "password123",
+    })
+    token = response.get_json()["access_token"]
+
+    return {"Authorization": f"Bearer {token}"}
+
+class TestAuthenticatedEndpoints:
+    def test_get_me_unauthorized(self, client):
+        response = client.get("/api/v1/users/me")
+        assert response.status_code == 401
+
+    def test_get_me_authorized(self, client, auth_headers):
+        response = client.get("/api/v1/users/me", headers=auth_headers)
+        assert response.status_code == 200
+        assert response.get_json()["email"] == "auth@example.com"
+```
+
+## Form Tests
+
+```python
+def test_login_form(client, db_session):
+    # Create user
+    user = User(email="test@example.com", name="Test")
+    user.set_password("password")
+    db_session.add(user)
+    db_session.commit()
+
+    response = client.post("/login", data={
+        "email": "test@example.com",
+        "password": "password",
+    }, follow_redirects=True)
+
+    assert response.status_code == 200
+    assert b"Dashboard" in response.data
+```
+
+## File Upload Tests
+
+```python
+from io import BytesIO
+
+def test_file_upload(client, auth_headers):
+    data = {
+        "file": (BytesIO(b"file content"), "test.txt"),
+    }
+
+    response = client.post(
+        "/api/v1/files/upload",
+        data=data,
+        content_type="multipart/form-data",
+        headers=auth_headers,
+    )
+
+    assert response.status_code == 201
+    assert response.get_json()["filename"] == "test.txt"
+```
+
+## CLI Command Tests
+
+```python
+def test_init_db_command(runner):
+    result = runner.invoke(args=["init-db"])
+    assert result.exit_code == 0
+    assert "Database initialized" in result.output
+
+def test_create_user_command(runner, db_session):
+    result = runner.invoke(args=[
+        "create-user",
+        "test@example.com",
+        "Test User",
+        "--admin",
+    ])
+
+    assert result.exit_code == 0
+    assert "Created user" in result.output
+
+    user = User.query.filter_by(email="test@example.com").first()
+    assert user is not None
+    assert user.is_admin is True
+```
+
+## Mocking External Services
+
+```python
+from unittest.mock import patch, MagicMock
+
+def test_send_email(client, db_session):
+    with patch("app.services.email.mail") as mock_mail:
+        response = client.post("/api/v1/users", json={
+            "email": "test@example.com",
+            "password": "password123",
+            "name": "Test User",
+        })
+
+        assert response.status_code == 201
+        mock_mail.send.assert_called_once()
+
+def test_external_api_call(client):
+    with patch("app.services.external.requests") as mock_requests:
+        mock_requests.get.return_value = MagicMock(
+            status_code=200,
+            json=lambda: {"data": "mocked"},
+        )
+
+        response = client.get("/api/v1/external-data")
+
+        assert response.status_code == 200
+        assert response.get_json()["data"] == "mocked"
+```
+
+## Parametrized Tests
+
+```python
+@pytest.mark.parametrize("email,expected_status", [
+    ("valid@example.com", 201),
+    ("also.valid@test.co.uk", 201),
+    ("invalid", 400),
+    ("missing@", 400),
+    ("@nodomain.com", 400),
+])
+def test_email_validation(client, email: str, expected_status: int):
+    response = client.post("/api/v1/users", json={
+        "email": email,
+        "password": "password123",
+        "name": "Test",
+    })
+
+    assert response.status_code == expected_status
+```
+
+## Test Markers
+
+```python
+# pytest.ini or pyproject.toml
+[tool.pytest.ini_options]
+markers = [
+    "slow: marks tests as slow",
+    "integration: requires database",
+]
+
+# Usage
+@pytest.mark.slow
+def test_heavy_computation():
+    ...
+
+@pytest.mark.integration
+def test_database_query(db_session):
+    ...
+
+# Run specific markers
+# pytest -m "not slow"
+# pytest -m integration
+```
+
+## Coverage Configuration
+
+```toml
+# pyproject.toml
+[tool.coverage.run]
+source = ["app"]
+omit = ["*/tests/*", "*/__init__.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+fail_under = 80
+```

package/configs/flask/settings.json

@@ -0,0 +1,35 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python *)",
+      "Bash(python3 *)",
+      "Bash(flask *)",
+      "Bash(gunicorn *)",
+      "Bash(pytest *)",
+      "Bash(ruff *)",
+      "Bash(mypy *)",
+      "Bash(alembic *)",
+      "Bash(uv *)",
+      "Bash(poetry *)",
+      "Bash(pip *)",
+      "Bash(pip3 *)",
+      "Read",
+      "Edit",
+      "Write"
+    ],
+    "deny": [
+      "Bash(git push *)",
+      "Bash(git push)",
+      "Bash(rm -rf *)",
+      "Read(.env)",
+      "Read(.env.*)",
+      "Read(**/secrets/**)",
+      "Read(**/*.pem)"
+    ]
+  },
+  "env": {
+    "FLASK_DEBUG": "1",
+    "PYTHONDONTWRITEBYTECODE": "1",
+    "PYTHONUNBUFFERED": "1"
+  }
+}