Reorganize Django's security policy page

[Sarah Boyce]

Django's security policy has grown organically over time. The page would probably benefit being restructured to make it easier to navigate/read/digest.

The current structure is roughly:

Django's security policy
├── Reporting security issues
│   ├── Respecting maintainer time
│   └── Reporting guidelines
├── How does Django evaluate a report
├── Supported versions
├── Security issue severity levels
├── How Django discloses security issues
├── Who receives advance notification
└── Requesting notifications

• Some of the reporting guidelines describe what a reporter should include, while others describe the scope of issues Django will consider.
• Supported versions and severity are also closely related to the assessment process but currently sit separately.
• There are two notification sections which could be grouped

One possible reorganization would be:

Django's security policy
├── Reporting security vulnerabilities
│   ├── How to report
│   ├── What to include
│   ├── Scope and reporting requirements
│   ├── Respecting maintainer time
│   └── AI-assisted reports
├── Assessing security vulnerabilities
│   ├── How Django evaluates a report
│   ├── Supported versions
│   ├── Security severity levels
│   └── Issues outside Django
├── Disclosing security vulnerabilities
│   ├── Coordinated disclosure
│   ├── Advance disclosure
│   ├── Public disclosure
│   └── Exceptional circumstances
└── Security notifications
    ├── Who receives advance notification
    ├── Who does not receive advance notification
    └── Requesting notifications

I am open to other grouping/structure suggestions and would welcome us looking at other open source security policies to guide us on what would be best here.

[Natalia Bidart]

Accepting following on agreement from the latest security meeting.

[OsmnvAslan]

I'll take this. Will post the proposed structure here before opening a PR.

[OsmnvAslan]

Here is the structure I intend to implement, based on the one proposed in the description, with the mapping of the existing content so it is clear this is a reorganization and not a rewrite of the policy itself:

Django's security policy
├── Reporting security vulnerabilities         (keeps label reporting-security-issues)
│   ├── How to report                          ← current intro: email, ack in 3 days, 90 days, PGP admonition
│   ├── What to include                        ← the "should include" bullets from "Respecting maintainer time"
│   │                                            + "Include a working proof of concept"
│   ├── Scope and reporting requirements       ← the six "must" subsections (supported deps, sanitized input,
│   │                                            8K headers/URLs, 2.5 MB body, feasible code, 100 KB DTL)
│   ├── Respecting maintainer time             (keeps label respecting-maintainer-time; the remaining
│   │                                            guidance: no CVSS/long analysis, one report at a time, no bulk)
│   └── AI-assisted reports                    ← unchanged, with "Note for AI tools" kept as a sub-subsection
├── Assessing security vulnerabilities
│   ├── How Django evaluates a report          (keeps label security-report-evaluation)
│   ├── Supported versions                     (keeps label security-support)
│   ├── Security severity levels               (keeps label severity-levels, used by release notes)
│   └── Issues outside Django                  ← the stdlib and third-party package paragraphs
├── Disclosing security vulnerabilities        (keeps label security-disclosure, used by howto-release-django)
│   ├── Coordinated disclosure                 ← intro + the "other frameworks in the ecosystem" paragraph
│   ├── Advance disclosure                     ← the "approximately one week before" notifications
│   ├── Public disclosure                      ← the "on the day of disclosure" steps + archive link
│   └── Exceptional circumstances              ← the "particularly time-sensitive" paragraph
└── Security notifications
    ├── Who receives advance notification      (keeps label security-notifications; the three groups)
    ├── Who does not receive advance notification ← "list is not public", "not a list of users",
    │                                               "security audit and scanning entities" admonition
    └── Requesting notifications               ← unchanged

Notes:

• All seven existing labels are preserved on the sections that carry the same content, so the references from the release notes (severity-levels), howto-release-django, api-stability, and the FAQ keep resolving. I'll add labels for the new top-level sections.
• The wording of the policy is not changed; edits are limited to the sentences needed to make the moved paragraphs read well in their new place (for example, "Respecting maintainer time" now points to "What to include" instead of repeating the list).
• Following the ticket title, I'd rename the page title to the singular "Django's security policy" and update the link text on the docs index page to match. Happy to leave the title as-is if you'd rather keep that out of scope.

If this grouping looks right, I'll open the PR; otherwise I'm happy to adjust before doing so.

[Jake Howard]

All in all, I like this new structure.

My main concerns with the old structure was "what to include" being too spread around. This definitely fixes that. I _think_ the separation between it and "Respecting maintainers time" makes sense, but let's see it in an actual PR.

I also think "Security notifications" can be indented, since it's a part of how we disclose vulnerabilities. It should probably live under "Advance disclosure", since that's what it's targetting. Doing this also keeps the top-level titles as the 3 main externally-visible processes (reporting, triaging, disclosing), in order.

[OsmnvAslan]

PR: ​https://github.com/django/django/pull/22052

Thanks Jake, "Security notifications" is now nested under "Advance disclosure", so the top level is the three processes in order.