ECC django-security Skill 实战指南：Django 认证、授权、注入防护与生产安全配置全解

本文以 ECC（Everything Claude Code）仓库中 .kiro/skills/django-security/SKILL.md 为核心，系统讲解 Django 应用的生产安全配置、认证授权设计、SQL 注入/XSS/CSRF 防护、文件上传校验、API 限流与密钥管理等完整实践。读完后你将掌握一套可直接套用的 Django 安全设置模板，并理解这些规范在 ECC 智能体工作流中如何被 django-reviewer Agent 和 Kiro Hooks 自动化执行。

Skill 定位：在 ECC 工作流中何时启用

该 Skill 的 YAML 元数据声明了它的触发语义：

---
name: django-security
description: Django security best practices, authentication, authorization, CSRF protection, SQL injection prevention, XSS prevention, and secure deployment configurations.
origin: ECC
---

文档明确了五类激活场景（When to Activate）：

• 搭建 Django 认证与授权体系；
• 实现用户权限与角色；
• 配置生产环境安全设置；
• 审查 Django 应用的安全问题；
• 将 Django 应用部署到生产环境。

在 ECC 项目内，Skill 是通过聊天框输入 / 打开菜单按需调用的工作流单元。按 .kiro/README.md 的说明，django-security 被列为 "Django security best practices, authentication, and CSRF/XSS prevention"，与 django-patterns、django-tdd 共同构成 Django 领域的技能矩阵。它不是孤立文档：agents/django-reviewer.md 在 Review Priorities 中将 SQL 注入、mark_safe 滥用、无因 @csrf_exempt、生产 DEBUG = True、硬编码 SECRET_KEY 列为 CRITICAL 级检查项，并在文末 Reference 一节显式指向 skill: django-security 作为安全配置清单的来源——也就是说，本 Skill 中的每一条配置规范，都对应着代码评审 Agent 的拦截规则。

核心安全配置：生产环境 Settings 模板

文档给出的生产配置是整个 Skill 的地基，覆盖 HTTPS 强制、安全响应头、Cookie 加固与密钥校验：

# settings/production.py
import os

DEBUG = False  # CRITICAL: Never use True in production

ALLOWED_HOSTS = os.environ.get('ALLOWED_HOSTS', '').split(',')

# Security headers
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_HSTS_SECONDS = 31536000  # 1 year
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True
SECURE_CONTENT_TYPE_NOSNIFF = True
SECURE_BROWSER_XSS_FILTER = True
X_FRAME_OPTIONS = 'DENY'

# HTTPS and Cookies
SESSION_COOKIE_HTTPONLY = True
CSRF_COOKIE_HTTPONLY = True
SESSION_COOKIE_SAMESITE = 'Lax'
CSRF_COOKIE_SAMESITE = 'Lax'

# Secret key (must be set via environment variable)
SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY')
if not SECRET_KEY:
    raise ImproperlyConfigured('DJANGO_SECRET_KEY environment variable is required')

# Password validation
AUTH_PASSWORD_VALIDATORS = [
    {
        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
        'OPTIONS': {
            'min_length': 12,
        }
    },
    {
        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
    },
]

这段配置的设计意图可以逐层拆解：

• DEBUG = False 与环境变量化 ALLOWED_HOSTS：DEBUG = True 会在出错时向客户端暴露完整堆栈与环境信息，因此评审 Agent 将其列为 CRITICAL；ALLOWED_HOSTS 从环境变量读取，使域名白名单可随部署环境变化而不改动代码。
• HSTS 三连：SECURE_HSTS_SECONDS = 31536000（1 年）配合 INCLUDE_SUBDOMAINS 与 PRELOAD，让浏览器强制子域也走 HTTPS 并进入预加载列表。
• Cookie 双加固：_SECURE（仅 HTTPS 传输）与 _HTTPONLY（禁止 JS 读取）分别抵御网络嗅探与 XSS 窃取 Cookie；SAMESITE = 'Lax' 则在保留正常顶级导航体验的同时阻断跨站携带 Cookie。
• 启动即失败：SECRET_KEY 缺失时直接抛出 ImproperlyConfigured，把"忘记配置密钥"这类事故从生产运行时提前到服务启动阶段。
• 四个密码校验器全开：相似度、最小长度 12、常用密码、纯数字，覆盖弱口令的常见形态。

认证（Authentication）

自定义 User 模型

文档以 AbstractUser 为基础构建自定义用户模型，用 email 作为登录名：

# apps/users/models.py
from django.contrib.auth.models import AbstractUser
from django.db import models

class User(AbstractUser):
    """Custom user model for better security."""

    email = models.EmailField(unique=True)
    phone = models.CharField(max_length=20, blank=True)

    USERNAME_FIELD = 'email'  # Use email as username
    REQUIRED_FIELDS = ['username']

    class Meta:
        db_table = 'users'
        verbose_name = 'User'
        verbose_name_plural = 'Users'

    def __str__(self):
        return self.email

# settings/base.py
AUTH_USER_MODEL = 'users.User'

使用 AbstractUser 而非 AbstractBaseUser 的关键在于保留 Django 内建的 is_staff、is_superuser、Groups/Permissions 全套能力，同时获得 email 唯一约束。注意 AUTH_USER_MODEL 必须在首个迁移生成之前设置——这一架构分层与 skills/django-patterns/SKILL.md 中推荐的 config/settings/ 分环境目录结构（base/development/production/test）相配套，安全相关的生产配置应只出现在 production.py 层。

密码哈希算法

# Django uses PBKDF2 by default. For stronger security:
PASSWORD_HASHERS = [
    'django.contrib.auth.hashers.Argon2PasswordHasher',
    'django.contrib.auth.hashers.PBKDF2PasswordHasher',
    'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
    'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
]

PASSWORD_HASHERS 是有序列表：首位的 Argon2 用于新密码哈希（内存硬化抗 GPU/ASIC 爆破），后三位作为兼容层保证存量密码仍可校验。

会话管理

# Session configuration
SESSION_ENGINE = 'django.contrib.sessions.backends.cache'  # Or 'db'
SESSION_CACHE_ALIAS = 'default'
SESSION_COOKIE_AGE = 3600 * 24 * 7  # 1 week
SESSION_SAVE_EVERY_REQUEST = False
SESSION_EXPIRE_AT_BROWSER_CLOSE = False  # Better UX, but less secure

选择 cache 后端意味着会话落在 Redis/内存缓存而非数据库，读写路径更快且避免会话表膨胀；SESSION_SAVE_EVERY_REQUEST = False 让 SESSION_COOKIE_AGE（7 天）成为唯一过期锚点，而非每次请求滚动续期——这是文档在可用性与安全之间做的显式取舍。

授权（Authorization）

模型级权限与视图混入

# models.py
from django.db import models
from django.contrib.auth.models import Permission

class Post(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    author = models.ForeignKey(User, on_delete=models.CASCADE)

    class Meta:
        permissions = [
            ('can_publish', 'Can publish posts'),
            ('can_edit_others', 'Can edit posts of others'),
        ]

    def user_can_edit(self, user):
        """Check if user can edit this post."""
        return self.author == user or user.has_perm('app.can_edit_others')

# views.py
from django.contrib.auth.mixins import LoginRequiredMixin, PermissionRequiredMixin
from django.views.generic import UpdateView

class PostUpdateView(LoginRequiredMixin, PermissionRequiredMixin, UpdateView):
    model = Post
    permission_required = 'app.can_edit_others'
    raise_exception = True  # Return 403 instead of redirect

    def get_queryset(self):
        """Only allow users to edit their own posts."""
        return Post.objects.filter(author=self.request.user)

这里有两层防线：PermissionRequiredMixin 做粗粒度权限门（是否持有 can_edit_others），get_queryset() 收窄到作者本人做对象级约束。raise_exception = True 使未授权访问返回 403 而非重定向，便于前端区分"未登录"与"无权限"。

DRF 自定义权限类

# permissions.py
from rest_framework import permissions

class IsOwnerOrReadOnly(permissions.BasePermission):
    """Allow only owners to edit objects."""

    def has_object_permission(self, request, view, obj):
        # Read permissions allowed for any request
        if request.method in permissions.SAFE_METHODS:
            return True

        # Write permissions only for owner
        return obj.author == request.user

class IsAdminOrReadOnly(permissions.BasePermission):
    """Allow admins to do anything, others read-only."""

    def has_permission(self, request, view):
        if request.method in permissions.SAFE_METHODS:
            return True
        return request.user and request.user.is_staff

class IsVerifiedUser(permissions.BasePermission):
    """Allow only verified users."""

    def has_permission(self, request, view):
        return request.user and request.user.is_authenticated and request.user.is_verified

这三个类分别对应"所有者语义""管理员语义""业务状态语义"三种授权模式。配套的实战项目模板 examples/django-api-CLAUDE.md 将这条原则固化为硬性规则："Permission classes on every view — never rely on default"，即每个视图必须显式声明权限类，禁止依赖 DRF 全局默认值。

基于角色的访问控制（RBAC）

# models.py
from django.contrib.auth.models import AbstractUser, Group

class User(AbstractUser):
    ROLE_CHOICES = [
        ('admin', 'Administrator'),
        ('moderator', 'Moderator'),
        ('user', 'Regular User'),
    ]
    role = models.CharField(max_length=20, choices=ROLE_CHOICES, default='user')

    def is_admin(self):
        return self.role == 'admin' or self.is_superuser

    def is_moderator(self):
        return self.role in ['admin', 'moderator']

# Mixins
class AdminRequiredMixin:
    """Mixin to require admin role."""

    def dispatch(self, request, *args, **kwargs):
        if not request.user.is_authenticated or not request.user.is_admin():
            from django.core.exceptions import PermissionDenied
            raise PermissionDenied
        return super().dispatch(request, *args, **kwargs)

从源码结构看，is_admin() 同时接受 role == 'admin' 或 is_superuser，把 Django 内建超级用户与新角色体系做了并集兼容，避免既有超管在引入 RBAC 后失去访问权。

SQL 注入防护

文档给出的核心判断标准：只要走 ORM 或参数化 raw()，就是安全的；任何字符串插值进 SQL 都是漏洞。

# GOOD: Django ORM automatically escapes parameters
def get_user(username):
    return User.objects.get(username=username)  # Safe

# GOOD: Using parameters with raw()
def search_users(query):
    return User.objects.raw('SELECT * FROM users WHERE username = %s', [query])

# BAD: Never directly interpolate user input
def get_user_bad(username):
    return User.objects.raw(f'SELECT * FROM users WHERE username = {username}')  # VULNERABLE!

# GOOD: Using filter with proper escaping
def get_users_by_email(email):
    return User.objects.filter(email__iexact=email)  # Safe

# GOOD: Using Q objects for complex queries
from django.db.models import Q
def search_users_complex(query):
    return User.objects.filter(
        Q(username__icontains=query) |
        Q(email__icontains=query)
    )  # Safe

必须使用原始 SQL 时的强制规范是参数与 SQL 文本分离：

# If you must use raw SQL, always use parameters
User.objects.raw(
    'SELECT * FROM users WHERE email = %s AND status = %s',
    [user_input_email, status]
)

这与 agents/django-reviewer.md 的 CRITICAL 清单首条完全一致："Raw SQL with f-strings or % formatting — use %s parameters or ORM"，评审 Agent 会把这类 diff 直接标记为阻断级问题。examples/django-api-CLAUDE.md 进一步将项目级约束写为："All queries use Django ORM — raw SQL only with .raw() and parameterized queries"。

XSS 防护

模板层转义

{# Django auto-escapes variables by default - SAFE #}
{{ user_input }}  {# Escaped HTML #}

{# Explicitly mark safe only for trusted content #}
{{ trusted_html|safe }}  {# Not escaped #}

{# Use template filters for safe HTML #}
{{ user_input|escape }}  {# Same as default #}
{{ user_input|striptags }}  {# Remove all HTML tags #}

{# JavaScript escaping #}
<script>
    var username = {{ username|escapejs }};
</script>

Django 模板引擎默认对所有变量做 HTML 转义，安全的关键在于克制使用 |safe：只标记可信内容，striptags 用于彻底剥离标签，escapejs 处理需要嵌入 JS 上下文的字符串。评审 Agent 在 CRITICAL 清单中明确："mark_safe on user input: Never without explicit escape() first"。

Safe String 处理

from django.utils.safestring import mark_safe
from django.utils.html import escape

# BAD: Never mark user input as safe without escaping
def render_bad(user_input):
    return mark_safe(user_input)  # VULNERABLE!

# GOOD: Escape first, then mark safe
def render_good(user_input):
    return mark_safe(escape(user_input))

# GOOD: Use format_html for HTML with variables
from django.utils.html import format_html

def greet_user(username):
    return format_html('<span class="user">{}</span>', escape(username))

format_html 是构造"HTML 中内嵌变量"时的首选，因为它对每个 {} 占位自动做转义，避免手动拼装 HTML 时遗漏。

安全响应头与自定义中间件

# settings.py
SECURE_CONTENT_TYPE_NOSNIFF = True  # Prevent MIME sniffing
SECURE_BROWSER_XSS_FILTER = True  # Enable XSS filter
X_FRAME_OPTIONS = 'DENY'  # Prevent clickjacking

# Custom middleware
from django.conf import settings

class SecurityHeaderMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        response = self.get_response(request)
        response['X-Content-Type-Options'] = 'nosniff'
        response['X-Frame-Options'] = 'DENY'
        response['X-XSS-Protection'] = '1; mode=block'
        response['Content-Security-Policy'] = "default-src 'self'"
        return response

X_FRAME_OPTIONS = 'DENY' 阻断点击劫持（页面不允许被任何 iframe 嵌套）；nosniff 阻止浏览器 MIME 类型嗅探；中间件则补上 Django 内置设置不直接管理的 CSP 头。

CSRF 防护

默认防护配置与用法

# settings.py - CSRF is enabled by default
CSRF_COOKIE_SECURE = True  # Only send over HTTPS
CSRF_COOKIE_HTTPONLY = False  # False so AJAX can read csrf token from document.cookie; SESSION_COOKIE_HTTPONLY remains True
CSRF_COOKIE_SAMESITE = 'Lax'  # Prevent CSRF in some cases
CSRF_TRUSTED_ORIGINS = ['https://example.com']  # Trusted domains

# Template usage
<form method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <button type="submit">Submit</button>
</form>

# AJAX requests
function getCookie(name) {
    let cookieValue = null;
    if (document.cookie && document.cookie !== '') {
        const cookies = document.cookie.split(';');
        for (let i = 0; i < cookies.length; i++) {
            const cookie = cookies[i].trim();
            if (cookie.substring(0, name.length + 1) === (name + '=')) {
                cookieValue = decodeURIComponent(cookie.substring(name.length + 1));
                break;
            }
        }
    }
    return cookieValue;
}

fetch('/api/endpoint/', {
    method: 'POST',
    headers: {
        'X-CSRFToken': getCookie('csrftoken'),
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(data)
});

一个值得注意的细节：CSRF_COOKIE_HTTPONLY = False 与生产模板中的 CSRF_COOKIE_HTTPONLY = True 看似矛盾，实为职责分离——CSRF token 需要前端 JS 通过 document.cookie 读出并放进 X-CSRFToken 请求头，故必须允许脚本读取；而会话 Cookie 保持 HTTPONLY，使 XSS 即使拿到页面执行权也无法读取 session。仓库主技能目录下的 skills/django-security/SKILL.md 中该配置为 CSRF_COOKIE_HTTPONLY = True 并注释 "Prevent JavaScript access"，代表不依赖 cookie 读 token 的更严格取向（如从服务端渲染注入 token）；两条路线的差异取决于前端取 token 的方式，配置时应对齐实际前端实现。

谨慎豁免 CSRF

from django.views.decorators.csrf import csrf_exempt

@csrf_exempt  # Only use when absolutely necessary!
def webhook_view(request):
    # Webhook from external service
    pass

@csrf_exempt 只应用于确实无法携带 token 的外部回调（Webhook）。评审规则将其约束为：非 Webhook 场景出现 @csrf_exempt 即视为 CRITICAL 问题；豁免后应在视图内改用签名校验等替代机制证明请求来源。

文件上传安全

文件校验

import os
from django.core.exceptions import ValidationError

def validate_file_extension(value):
    """Validate file extension."""
    ext = os.path.splitext(value.name)[1]
    valid_extensions = ['.jpg', '.jpeg', '.png', '.gif', '.pdf']
    if not ext.lower() in valid_extensions:
        raise ValidationError('Unsupported file extension.')

def validate_file_size(value):
    """Validate file size (max 5MB)."""
    filesize = value.size
    if filesize > 5 * 1024 * 1024:
        raise ValidationError('File too large. Max size is 5MB.')

# models.py
class Document(models.Model):
    file = models.FileField(
        upload_to='documents/',
        validators=[validate_file_extension, validate_file_size]
    )

安全存储

# settings.py
MEDIA_ROOT = '/var/www/media/'
MEDIA_URL = '/media/'

# Use a separate domain for media in production
MEDIA_DOMAIN = 'https://media.example.com'

# Don't serve user uploads directly
# Use whitenoise or a CDN for static files
# Use a separate server or S3 for media files

存储侧原则是"上传物不进主站"：媒体走独立域名或对象存储，避免上传文件与业务页面共享 SameSite 上下文。

值得深挖的是，仓库主技能目录中的 skills/django-security/SKILL.md 提供了本 Kiro 版本的增强实现——仅校验扩展名可被重命名绕过（.jpg 后缀的 PHP 脚本），因此增强版改用魔数（magic bytes）做内容级校验：

import magic  # pip install python-magic

ALLOWED_MIMES = {
    'image/jpeg', 'image/png', 'image/gif', 'application/pdf',
}

MIME_TO_EXTENSIONS = {
    'image/jpeg': {'.jpg', '.jpeg'},
    'image/png': {'.png'},
    'image/gif': {'.gif'},
    'application/pdf': {'.pdf'},
}

def validate_file_type(value):
    """Validate file type using magic bytes and cross-check extension."""
    mime = magic.from_buffer(value.read(2048), mime=True)
    value.seek(0)

    if mime not in ALLOWED_MIMES:
        raise ValidationError('Unsupported file type.')

    ext = os.path.splitext(value.name)[1].lower()
    if ext not in MIME_TO_EXTENSIONS.get(mime, set()):
        raise ValidationError('File extension does not match file content.')

它读取文件头 2KB 判定真实 MIME，并交叉比对"声明的扩展名与内容类型必须一致"；对无法安装 libmagic 的精简容器，增强版还给出纯 Python 的 filetype 包替代方案。生产项目落地时建议直接采用这一双层校验。

API 安全

限流（Rate Limiting）

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': [
        'rest_framework.throttling.AnonRateThrottle',
        'rest_framework.throttling.UserRateThrottle'
    ],
    'DEFAULT_THROTTLE_RATES': {
        'anon': '100/day',
        'user': '1000/day',
        'upload': '10/hour',
    }
}

# Custom throttle
from rest_framework.throttling import UserRateThrottle

class BurstRateThrottle(UserRateThrottle):
    scope = 'burst'
    rate = '60/min'

class SustainedRateThrottle(UserRateThrottle):
    scope = 'sustained'
    rate = '1000/day'

限流策略采用"匿名宽、登录严、敏感操作最严"的分级思路：anon 100/day 压住爬虫与撞库的匿名流量，upload 10/hour 这类独立 scope 用于上传等昂贵操作。自定义 Throttle 类把"突发速率"（burst 60/min）与"持续速率"（sustained 1000/day）拆成两个独立维度，可在同一视图上同时挂载。评审 Agent 的 HIGH 级检查中同样包含"No throttling on auth endpoints: Login/registration open to brute force"，即登录/注册端点是限流的第一优先级。

API 认证

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.TokenAuthentication',
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticated',
    ],
}

# views.py
from rest_framework.decorators import api_view, permission_classes
from rest_framework.permissions import IsAuthenticated

@api_view(['GET', 'POST'])
@permission_classes([IsAuthenticated])
def protected_view(request):
    return Response({'message': 'You are authenticated'})

多认证类并存让同一 API 同时支持 Token（简单机器对机器）、Session（浏览器端）与 JWT（无状态移动端）三种客户端形态；默认权限类 IsAuthenticated 保证未显式声明权限的视图也是"需登录"而非"完全开放"，配合前文"每个视图必须显式权限类"的规则形成双保险。examples/django-api-CLAUDE.md 中还给出了 JWT 的落地参数：access token 15 分钟 + refresh token 7 天，并启用 token 黑名单支持登出。

安全头与内容安全策略（CSP）

# settings.py
CSP_DEFAULT_SRC = "'self'"
CSP_SCRIPT_SRC = "'self' https://cdn.example.com"
CSP_STYLE_SRC = "'self' 'unsafe-inline'"
CSP_IMG_SRC = "'self' data: https:"
CSP_CONNECT_SRC = "'self' https://api.example.com"

# Middleware
class CSPMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        response = self.get_response(request)
        response['Content-Security-Policy'] = (
            f"default-src {CSP_DEFAULT_SRC}; "
            f"script-src {CSP_SCRIPT_SRC}; "
            f"style-src {CSP_STYLE_SRC}; "
            f"img-src {CSP_IMG_SRC}; "
            f"connect-src {CSP_CONNECT_SRC}"
        )
        return response

CSP 以白名单方式逐指令声明：默认只允许同源（'self'），再按脚本 CDN、图片协议、API 域名逐项放行。'unsafe-inline' 只出现在 style 指令（常见于内联样式场景）；script 指令保持无 inline、无 unsafe-eval，这是 CSP 防 XSS 的核心纪律。若项目使用 django-csp 类中间件库，CSP_* 设置键可直接被其消费，此处手写中间件则展示了同等语义的最小实现。

密钥与环境变量管理

# Use python-decouple or django-environ
import environ

env = environ.Env(
    # set casting, default value
    DEBUG=(bool, False)
)

# reading .env file
environ.Env.read_env()

SECRET_KEY = env('DJANGO_SECRET_KEY')
DATABASE_URL = env('DATABASE_URL')
ALLOWED_HOSTS = env.list('ALLOWED_HOSTS')

# .env file — NEVER commit this to version control
DEBUG=False
SECRET_KEY=REPLACE_WITH_SECURE_KEY
DATABASE_URL=postgresql://USER:PASSWORD@HOST:PORT/DBNAME
ALLOWED_HOSTS=example.com,www.example.com

django-environ 的三个要点在示例中都有体现：声明类型转换（DEBUG=(bool, False)，且默认值为 False——安全侧的 fail-safe 方向）、env.list() 自动把逗号分隔串解析为列表、.env 文件绝不入版本库。SECRET_KEY 必须来自环境注入这一条，在评审 Agent 中同样是 CRITICAL 拦截项。

安全事件日志

# settings.py
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'file': {
            'level': 'WARNING',
            'class': 'logging.FileHandler',
            'filename': '/var/log/django/security.log',
        },
        'console': {
            'level': 'INFO',
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'django.security': {
            'handlers': ['file', 'console'],
            'level': 'WARNING',
            'propagate': True,
        },
        'django.request': {
            'handlers': ['file'],
            'level': 'ERROR',
            'propagate': False,
        },
    },
}

Django 内置的 django.security logger 会自动记录 CSRF 失败、404 越权尝试、Bad Request 等事件（如 django.security.csrf、django.security.disallowed_host）。这份配置把该通道单独落盘到 /var/log/django/security.log，与安全告警、审计工具对接；django.request 则只记 ERROR 且不传播，避免请求异常淹没安全日志。

快速安全清单（Quick Security Checklist）

文档末尾的清单是整篇规范的浓缩验收表，可作为上线前逐项核对：

检查项	说明
DEBUG = False	生产环境绝不允许开启 DEBUG
仅 HTTPS	强制 SSL、安全 Cookie
强密钥	SECRET_KEY 一律走环境变量
密码校验	启用全部密码校验器
CSRF 防护	默认开启，不要关闭
XSS 防护	依赖 Django 自动转义，用户输入禁用 |safe
SQL 注入	使用 ORM，绝不拼接查询字符串
文件上传	校验文件类型与大小
限流	为 API 端点配置 Throttle
安全响应头	CSP、X-Frame-Options、HSTS
日志	记录安全事件
依赖更新	保持 Django 与依赖库版本更新

与 ECC 自动化机制的衔接：让规范被强制执行

在 ECC 中，这份 Skill 不只是给人读的清单，而是接入了自动化的质量防线：

1. django-reviewer Agent：agents/django-reviewer.md 的 CRITICAL/HIGH 检查项与本文各节一一对应（SQL 注入、mark_safe、csrf_exempt、DEBUG、SECRET_KEY、限流缺失等），并以 "Approve / Warning / Block" 三级结论输出，其评审视角是"Would this code safely serve 10,000 concurrent users without data loss, security breach"。它同时建议配套运行 python manage.py check、ruff check .、bandit -r . -ll 等诊断命令。
2. 敏感目录 Hook：.kiro/hooks/security-check-on-create.kiro.hook 定义了一个 Kiro IDE Hook——只要新建文件落在 **/auth/**、**/api/**、**/middleware/** 目录，就会自动触发 Agent 检查"硬编码密钥、缺失输入校验、SQL 注入风险、缺失认证/授权检查"，即把本 Skill 的检查点前置到文件创建时刻。
3. 技能协同：架构与 ORM 规范由 skills/django-patterns/SKILL.md 承接（分环境 settings、apps 分层、DRF 设计），测试验证由 django-tdd、django-verification 技能承接，三者与 django-security 共同覆盖 Django 从结构、安全到验证的完整生命周期。

适用前提与边界

• 本文所有配置与代码示例以 .kiro/skills/django-security/SKILL.md 为准，面向使用 Django ORM/DRF 的标准项目；涉及 djangorestframework-simplejwt、django-environ、python-magic/filetype 的示例需要相应安装第三方包。
• CSRF_COOKIE_HTTPONLY、文件校验强度等存在仓库内两个版本差异（.kiro/ 版本与 skills/ 版本），采用时应以自身前端取 token 方式与依赖环境为准，并保持与 examples/django-api-CLAUDE.md 示例项目中的项目级规则一致。
• 文档结尾的结论同样适用于工程实践："Security is a process, not a product"——定期重跑评审 Agent、复核对标清单、跟进依赖安全更新，才是这套配置长期生效的保障。