# Report a security issue

[//]: # (ATTENTION: This is the .MD version of docs/security.rst. Any changes should also be made in the RST version.)

We take security very seriously.
Your input and feedback on our security
is always appreciated.

You can send urgent or sensitive reports via [GitHub Security Advisory](https://github.com/twisted/twisted/security/advisories/new).

If you prefer, you can send via email to <security@twistedmatrix.com>.
You may use our PGP public key if you wish. We will create a GitHub
security advisory to coordinate a fix. Include your GitHub username so
that we add you as a collaborator on the advisory. See
[GHSA-c2jg-hw38-jrqq](https://github.com/twisted/twisted/security/advisories/GHSA-c2jg-hw38-jrqq)
for an example. We'll get back to you as soon as we can.

Twisted is an all volunteer project and there may be some delay before
we can respond.

Feel free to follow up if you think an unreasonable amount of time has
elapsed without a response!

All releases, including security releases, are announced on the mailing
list. Consider subscribing to receive notification about the
availability of a security fix.

# Security Procedure for Developers

The goal of the normal Twisted development procedure is to make all
steps transparent and record all information at all times in a public
location - either the issue tracker or a branch.

The goal of the security variation of the Twisted development procedure
is to keep track of progress resolving security issues while minimizing
the window of time where information useful to attackers is available
before a fix for the issue is available to Twisted users.

This process is intended as a helpful recommendation. Elements of it may
be followed more or less strictly depending on the severity of the issue
in question:

1.  Begin by filing a ticket which does not describe the issue and
    simply says 'security issue, description pending' and has the
    'security' keyword.
2.  Create a security advisory in GitHub using the [GitHub
    UI](https://github.com/twisted/twisted/security/advisories/new).
    This will trigger the creation of a private repository that can be
    use for developing a patch. This automatically created private
    repository is also used to review the PR in private.
3.  Make the required changes to fix the security issue in the new
    private repository.
4.  Create a new PR using the GitHub security advisory UI. This will
    generate a private PR. Request the review and get the approval for
    the PR. Don't merge the PR after approval. In the PR description
    define the desired merge commit message. The PR will be merged by
    the release manager at the same time with the first release
    candidate.
5.  Automated notifications for the private repository and private PR
    are limited. Try to communicate over IRC, gitter or other means to
    find a person to review the new PR. Coordinate with the release
    manager. More info about the release process can be found on the
    [release process](docs/development/release-process.rst) dedicated page.
6.  We are not aware of a way to securely transmit our code to our
    public continuous integration systems. Reviewers should manually run
    the automated tests on their local forks of the new private
    repository.

Aside from hiding the details of the issue while development is ongoing,
all of the normal policies apply. Security fixes require unit tests,
code review, etc.

## PGP key for email communication

Below is the PGP key for <security@twistedmatrix.com>:

    -----BEGIN PGP PUBLIC KEY BLOCK-----
    Version: GnuPG v2.0.22 (Darwin)

[encoded data, 24702 characters]
    2pOVp6XTYdUW
    =HDSq
    -----END PGP PUBLIC KEY BLOCK-----

# Security Audit

We need to do a full audit of Twisted, module by module. This document
list the sort of things you want to look for when doing this, or when
writing your own code.

## Bad input

Any place we receive untrusted data, we need to be careful. In some
cases we are not careful enough. For example, in HTTP there are many
places where strings need to be converted to ints, so we use `int()` .
The problem is that this will accept negative or hexadecimal
(<span class="title-ref">0x123</span>) numbers as well, whereas the
protocol should only accept positive numbers.

## Resource Exhaustion and DoS

Make sure we never allow users to create arbitrarily large strings or
files. Some of the protocols still have issues like this. Place a limit
which allows reasonable use but will cut off huge requests, and allow
changing of this limit.

Another operation to look out for are exceptions. They can fill up logs
and take a lot of CPU time to render in web pages.
pandoc version 3.1.8