secure 0.3.0__tar.gz → 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {secure-0.3.0 → secure-1.0.0}/LICENSE +1 -1
- secure-1.0.0/MANIFEST.in +2 -0
- secure-1.0.0/PKG-INFO +348 -0
- secure-1.0.0/README.md +324 -0
- secure-1.0.0/pyproject.toml +37 -0
- secure-1.0.0/secure/__init__.py +29 -0
- secure-1.0.0/secure/headers/__init__.py +27 -0
- secure-1.0.0/secure/headers/base_header.py +120 -0
- secure-1.0.0/secure/headers/cache_control.py +257 -0
- secure-1.0.0/secure/headers/content_security_policy.py +305 -0
- secure-1.0.0/secure/headers/cross_origin_embedder_policy.py +100 -0
- secure-1.0.0/secure/headers/cross_origin_opener_policy.py +111 -0
- secure-1.0.0/secure/headers/custom_header.py +56 -0
- secure-1.0.0/secure/headers/permissions_policy.py +412 -0
- secure-1.0.0/secure/headers/referrer_policy.py +168 -0
- secure-1.0.0/secure/headers/server.py +59 -0
- secure-1.0.0/secure/headers/strict_transport_security.py +118 -0
- secure-1.0.0/secure/headers/x_content_type_options.py +76 -0
- secure-1.0.0/secure/headers/x_frame_options.py +89 -0
- secure-1.0.0/secure/py.typed +0 -0
- secure-1.0.0/secure/secure.py +283 -0
- secure-1.0.0/secure.egg-info/PKG-INFO +348 -0
- secure-1.0.0/secure.egg-info/SOURCES.txt +24 -0
- {secure-0.3.0 → secure-1.0.0}/secure.egg-info/top_level.txt +1 -0
- secure-0.3.0/MANIFEST.in +0 -3
- secure-0.3.0/PKG-INFO +0 -186
- secure-0.3.0/README.md +0 -166
- secure-0.3.0/secure/__init__.py +0 -11
- secure-0.3.0/secure/headers.py +0 -860
- secure-0.3.0/secure/secure.py +0 -239
- secure-0.3.0/secure.egg-info/PKG-INFO +0 -186
- secure-0.3.0/secure.egg-info/SOURCES.txt +0 -11
- secure-0.3.0/setup.py +0 -143
- {secure-0.3.0 → secure-1.0.0}/secure.egg-info/dependency_links.txt +0 -0
- {secure-0.3.0 → secure-1.0.0}/setup.cfg +0 -0
secure-1.0.0/MANIFEST.in
ADDED
secure-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,348 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: secure
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: A lightweight package that adds security headers for Python web frameworks.
|
|
5
|
+
Author-email: Caleb Kinney <caleb@typeerror.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/TypeError/secure
|
|
8
|
+
Project-URL: Documentation, https://github.com/TypeError/secure/tree/main/docs
|
|
9
|
+
Project-URL: Repository, https://github.com/TypeError/secure
|
|
10
|
+
Project-URL: Issue-Tracker, https://github.com/TypeError/secure/issues
|
|
11
|
+
Keywords: security,headers,web,framework,HTTP
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Typing :: Typed
|
|
18
|
+
Classifier: Operating System :: OS Independent
|
|
19
|
+
Classifier: Intended Audience :: Developers
|
|
20
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE
|
|
24
|
+
|
|
25
|
+
# secure.py
|
|
26
|
+
|
|
27
|
+
_A simple, yet powerful way to secure your Python web applications across multiple frameworks._
|
|
28
|
+
|
|
29
|
+
[](https://pypi.org/project/secure/)
|
|
30
|
+
[](https://pypi.org/project/secure/)
|
|
31
|
+
[](https://github.com/astral-sh/ruff)
|
|
32
|
+
[](https://pepy.tech/project/secure)
|
|
33
|
+
[](https://github.com/TypeError/secure/blob/main/LICENSE)
|
|
34
|
+
[](https://github.com/TypeError/secure/stargazers)
|
|
35
|
+
|
|
36
|
+
## **Introduction**
|
|
37
|
+
|
|
38
|
+
In today's web landscape, security is paramount. **secure.py** is a lightweight Python library designed to effortlessly add **security headers** to your web applications, protecting them from common vulnerabilities. Whether you're using **Django**, **Flask**, **FastAPI**, or any other popular framework, `secure.py` provides a unified API to enhance your application's security posture.
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## **Why Use secure.py?**
|
|
43
|
+
|
|
44
|
+
- 🔒 **Apply Essential Security Headers**: Implement headers like CSP, HSTS, and more with minimal effort.
|
|
45
|
+
- 🛠️ **Consistent API Across Frameworks**: A unified approach for different web frameworks.
|
|
46
|
+
- ⚙️ **Customizable with Secure Defaults**: Start secure out-of-the-box and customize as needed.
|
|
47
|
+
- 🚀 **Easy Integration**: Compatible with Python's most-used frameworks.
|
|
48
|
+
- 🐍 **Modern Pythonic Design**: Leverages Python 3.10+ features for cleaner and more efficient code.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## **Supported Frameworks**
|
|
53
|
+
|
|
54
|
+
**secure.py** supports the following Python web frameworks:
|
|
55
|
+
|
|
56
|
+
| Framework | Documentation |
|
|
57
|
+
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
58
|
+
| [aiohttp](https://docs.aiohttp.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#aiohttp) |
|
|
59
|
+
| [Bottle](https://bottlepy.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#bottle) |
|
|
60
|
+
| [CherryPy](https://cherrypy.dev/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#cherrypy) |
|
|
61
|
+
| [Django](https://www.djangoproject.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#django) |
|
|
62
|
+
| [Falcon](https://falconframework.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#falcon) |
|
|
63
|
+
| [FastAPI](https://fastapi.tiangolo.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#fastapi) |
|
|
64
|
+
| [Flask](http://flask.pocoo.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#flask) |
|
|
65
|
+
| [Masonite](https://docs.masoniteproject.com/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#masonite) |
|
|
66
|
+
| [Morepath](https://morepath.readthedocs.io) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#morepath) |
|
|
67
|
+
| [Pyramid](https://trypyramid.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#pyramid) |
|
|
68
|
+
| [Quart](https://quart.palletsprojects.com/en/latest/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#quart) |
|
|
69
|
+
| [Responder](https://responder.kennethreitz.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#responder) |
|
|
70
|
+
| [Sanic](https://sanicframework.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#sanic) |
|
|
71
|
+
| [Starlette](https://www.starlette.io/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#starlette) |
|
|
72
|
+
| [Tornado](https://www.tornadoweb.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#tornado) |
|
|
73
|
+
| [TurboGears](https://turbogears.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#turbogears) |
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## **Features**
|
|
78
|
+
|
|
79
|
+
- 🔒 **Secure Headers**: Automatically apply headers like `Strict-Transport-Security`, `X-Frame-Options`, and more.
|
|
80
|
+
- 🛠️ **Customizable Policies**: Flexibly build your own security policies using method chaining.
|
|
81
|
+
- 🌐 **Framework Integration**: Compatible with various frameworks, ensuring cross-compatibility.
|
|
82
|
+
- 🚀 **No External Dependencies**: Lightweight and easy to include in any project.
|
|
83
|
+
- 🧩 **Easy to Use**: Integrate security headers in just a few lines of code.
|
|
84
|
+
- ⚡ **Asynchronous Support**: Async support for modern frameworks like **FastAPI** and **Starlette**.
|
|
85
|
+
- 📝 **Enhanced Type Hinting**: Complete type annotations for better developer experience.
|
|
86
|
+
- 📚 **Attribution to Trusted Sources**: Implements recommendations from MDN and OWASP.
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## **Requirements**
|
|
91
|
+
|
|
92
|
+
- **Python 3.10** or higher
|
|
93
|
+
|
|
94
|
+
This library leverages modern Python features introduced in Python 3.10 and 3.11, such as:
|
|
95
|
+
|
|
96
|
+
- **Union Type Operator (`|`)**: Simplifies type annotations.
|
|
97
|
+
- **Structural Pattern Matching (`match` statement)**: Enhances control flow.
|
|
98
|
+
- **Improved Type Hinting and Annotations**: Provides better code clarity and maintenance.
|
|
99
|
+
- **`cached_property`**: Optimize memory usage and performance.
|
|
100
|
+
|
|
101
|
+
**Note:** If you're using an older version of Python (3.6 to 3.9), please use version **0.3.0** of this library, which maintains compatibility with those versions.
|
|
102
|
+
|
|
103
|
+
- **Dependencies**
|
|
104
|
+
|
|
105
|
+
This library has no external dependencies outside of the Python Standard Library.
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## **Installation**
|
|
110
|
+
|
|
111
|
+
You can install secure.py using pip, pipenv, or poetry:
|
|
112
|
+
|
|
113
|
+
**pip**:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
pip install secure
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
**Pipenv**:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
pipenv install secure
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
**Poetry**:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
poetry add secure
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## **Getting Started**
|
|
134
|
+
|
|
135
|
+
Once installed, you can quickly integrate `secure.py` into your project:
|
|
136
|
+
|
|
137
|
+
### Synchronous Usage
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
import secure
|
|
141
|
+
|
|
142
|
+
# Initialize secure headers with default settings
|
|
143
|
+
secure_headers = secure.Secure.with_default_headers()
|
|
144
|
+
|
|
145
|
+
# Apply the headers to your framework response object
|
|
146
|
+
secure_headers.set_headers(response)
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Asynchronous Usage
|
|
150
|
+
|
|
151
|
+
For frameworks like **FastAPI** and **Starlette** that support asynchronous operations, use the async method:
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
import secure
|
|
155
|
+
|
|
156
|
+
# Initialize secure headers with default settings
|
|
157
|
+
secure_headers = secure.Secure.with_default_headers()
|
|
158
|
+
|
|
159
|
+
# Apply the headers asynchronously to your framework response object
|
|
160
|
+
await secure_headers.set_headers_async(response)
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### **Example Usage**
|
|
164
|
+
|
|
165
|
+
```python
|
|
166
|
+
import secure
|
|
167
|
+
|
|
168
|
+
# Create a Secure instance with default headers
|
|
169
|
+
secure_headers = secure.Secure.with_default_headers()
|
|
170
|
+
|
|
171
|
+
# Apply default secure headers to a response object
|
|
172
|
+
secure_headers.set_headers(response)
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## **Default Secure Headers**
|
|
178
|
+
|
|
179
|
+
By default, `secure.py` applies the following headers when using `with_default_headers()`:
|
|
180
|
+
|
|
181
|
+
```http
|
|
182
|
+
Cache-Control: no-store
|
|
183
|
+
Cross-Origin-Opener-Policy: same-origin
|
|
184
|
+
Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; object-src 'none'
|
|
185
|
+
Strict-Transport-Security: max-age=31536000
|
|
186
|
+
Permissions-Policy: geolocation=(), microphone=(), camera=()
|
|
187
|
+
Referrer-Policy: strict-origin-when-cross-origin
|
|
188
|
+
Server:
|
|
189
|
+
X-Content-Type-Options: nosniff
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## **Policy Builders**
|
|
195
|
+
|
|
196
|
+
`secure.py` allows you to customize headers such as **Content-Security-Policy** and **Permissions-Policy** with ease:
|
|
197
|
+
|
|
198
|
+
### **Content-Security-Policy Example**
|
|
199
|
+
|
|
200
|
+
```python
|
|
201
|
+
import secure
|
|
202
|
+
|
|
203
|
+
# Build a custom CSP policy
|
|
204
|
+
csp = (
|
|
205
|
+
secure.ContentSecurityPolicy()
|
|
206
|
+
.default_src("'self'")
|
|
207
|
+
.script_src("'self'", "cdn.example.com")
|
|
208
|
+
.style_src("'unsafe-inline'")
|
|
209
|
+
.img_src("'self'", "images.example.com")
|
|
210
|
+
.connect_src("'self'", "api.example.com")
|
|
211
|
+
)
|
|
212
|
+
|
|
213
|
+
# Apply it to secure headers
|
|
214
|
+
secure_headers = secure.Secure(csp=csp)
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
**Resulting HTTP headers:**
|
|
218
|
+
|
|
219
|
+
```http
|
|
220
|
+
Content-Security-Policy: default-src 'self'; script-src 'self' cdn.example.com; style-src 'unsafe-inline'; img-src 'self' images.example.com; connect-src 'self' api.example.com
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
### **Permissions-Policy Example**
|
|
224
|
+
|
|
225
|
+
```python
|
|
226
|
+
import secure
|
|
227
|
+
|
|
228
|
+
# Build a custom Permissions Policy
|
|
229
|
+
permissions = (
|
|
230
|
+
secure.PermissionsPolicy()
|
|
231
|
+
.geolocation("'self'")
|
|
232
|
+
.camera("'none'")
|
|
233
|
+
.microphone("'none'")
|
|
234
|
+
)
|
|
235
|
+
|
|
236
|
+
# Apply it to secure headers
|
|
237
|
+
secure_headers = secure.Secure(permissions=permissions)
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
**Resulting HTTP headers:**
|
|
241
|
+
|
|
242
|
+
```http
|
|
243
|
+
Permissions-Policy: geolocation=('self'), camera=('none'), microphone=('none')
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## **Framework Examples**
|
|
249
|
+
|
|
250
|
+
### **FastAPI**
|
|
251
|
+
|
|
252
|
+
```python
|
|
253
|
+
from fastapi import FastAPI
|
|
254
|
+
|
|
255
|
+
from secure import Secure
|
|
256
|
+
|
|
257
|
+
app = FastAPI()
|
|
258
|
+
secure_headers = Secure.with_default_headers()
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
@app.middleware("http")
|
|
262
|
+
async def add_security_headers(request, call_next):
|
|
263
|
+
response = await call_next(request)
|
|
264
|
+
await secure_headers.set_headers_async(response)
|
|
265
|
+
return response
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
@app.get("/")
|
|
269
|
+
def read_root():
|
|
270
|
+
return {"Hello": "World"}
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
### Flask
|
|
274
|
+
|
|
275
|
+
```python
|
|
276
|
+
from flask import Flask, Response
|
|
277
|
+
|
|
278
|
+
from secure import Secure
|
|
279
|
+
|
|
280
|
+
app = Flask(__name__)
|
|
281
|
+
secure_headers = Secure.with_default_headers()
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
@app.after_request
|
|
285
|
+
def add_security_headers(response: Response):
|
|
286
|
+
secure_headers.set_headers(response)
|
|
287
|
+
return response
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
@app.route("/")
|
|
291
|
+
def home():
|
|
292
|
+
return "Hello, world"
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
if __name__ == "__main__":
|
|
296
|
+
app.run()
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
---
|
|
300
|
+
|
|
301
|
+
## **Documentation**
|
|
302
|
+
|
|
303
|
+
For more details, including advanced configurations and integration examples, please visit the **[full documentation](https://github.com/TypeError/secure/tree/main/docs)**.
|
|
304
|
+
|
|
305
|
+
---
|
|
306
|
+
|
|
307
|
+
## **Attribution**
|
|
308
|
+
|
|
309
|
+
This library implements security recommendations from trusted sources:
|
|
310
|
+
|
|
311
|
+
- [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/))
|
|
312
|
+
- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/))
|
|
313
|
+
|
|
314
|
+
We have included attribution comments in the source code where appropriate.
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## **Resources**
|
|
319
|
+
|
|
320
|
+
- [OWASP - Secure Headers Project](https://owasp.org/www-project-secure-headers/)
|
|
321
|
+
- [Mozilla Web Security Guidelines](https://infosec.mozilla.org/guidelines/web_security)
|
|
322
|
+
- [MDN Web Docs: Security Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#security)
|
|
323
|
+
- [web.dev: Security Best Practices](https://web.dev)
|
|
324
|
+
- [The World Wide Web Consortium (W3C)](https://www.w3.org)
|
|
325
|
+
|
|
326
|
+
---
|
|
327
|
+
|
|
328
|
+
### **License**
|
|
329
|
+
|
|
330
|
+
This project is licensed under the terms of the **[MIT License](https://opensource.org/licenses/MIT)**.
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
|
|
334
|
+
## **Contributing**
|
|
335
|
+
|
|
336
|
+
Contributions are welcome! If you'd like to contribute to `secure.py`, please feel free to open an issue or submit a pull request on **[GitHub](https://github.com/TypeError/secure)**.
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## **Changelog**
|
|
341
|
+
|
|
342
|
+
For a detailed list of changes, please refer to the **[CHANGELOG](https://github.com/TypeError/secure/blob/main/CHANGELOG.md)**.
|
|
343
|
+
|
|
344
|
+
---
|
|
345
|
+
|
|
346
|
+
## **Acknowledgements**
|
|
347
|
+
|
|
348
|
+
We would like to thank the contributors of MDN Web Docs and OWASP Secure Headers Project for their invaluable resources and guidelines that help make the web a safer place.
|
secure-1.0.0/README.md
ADDED
|
@@ -0,0 +1,324 @@
|
|
|
1
|
+
# secure.py
|
|
2
|
+
|
|
3
|
+
_A simple, yet powerful way to secure your Python web applications across multiple frameworks._
|
|
4
|
+
|
|
5
|
+
[](https://pypi.org/project/secure/)
|
|
6
|
+
[](https://pypi.org/project/secure/)
|
|
7
|
+
[](https://github.com/astral-sh/ruff)
|
|
8
|
+
[](https://pepy.tech/project/secure)
|
|
9
|
+
[](https://github.com/TypeError/secure/blob/main/LICENSE)
|
|
10
|
+
[](https://github.com/TypeError/secure/stargazers)
|
|
11
|
+
|
|
12
|
+
## **Introduction**
|
|
13
|
+
|
|
14
|
+
In today's web landscape, security is paramount. **secure.py** is a lightweight Python library designed to effortlessly add **security headers** to your web applications, protecting them from common vulnerabilities. Whether you're using **Django**, **Flask**, **FastAPI**, or any other popular framework, `secure.py` provides a unified API to enhance your application's security posture.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## **Why Use secure.py?**
|
|
19
|
+
|
|
20
|
+
- 🔒 **Apply Essential Security Headers**: Implement headers like CSP, HSTS, and more with minimal effort.
|
|
21
|
+
- 🛠️ **Consistent API Across Frameworks**: A unified approach for different web frameworks.
|
|
22
|
+
- ⚙️ **Customizable with Secure Defaults**: Start secure out-of-the-box and customize as needed.
|
|
23
|
+
- 🚀 **Easy Integration**: Compatible with Python's most-used frameworks.
|
|
24
|
+
- 🐍 **Modern Pythonic Design**: Leverages Python 3.10+ features for cleaner and more efficient code.
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## **Supported Frameworks**
|
|
29
|
+
|
|
30
|
+
**secure.py** supports the following Python web frameworks:
|
|
31
|
+
|
|
32
|
+
| Framework | Documentation |
|
|
33
|
+
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
34
|
+
| [aiohttp](https://docs.aiohttp.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#aiohttp) |
|
|
35
|
+
| [Bottle](https://bottlepy.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#bottle) |
|
|
36
|
+
| [CherryPy](https://cherrypy.dev/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#cherrypy) |
|
|
37
|
+
| [Django](https://www.djangoproject.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#django) |
|
|
38
|
+
| [Falcon](https://falconframework.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#falcon) |
|
|
39
|
+
| [FastAPI](https://fastapi.tiangolo.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#fastapi) |
|
|
40
|
+
| [Flask](http://flask.pocoo.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#flask) |
|
|
41
|
+
| [Masonite](https://docs.masoniteproject.com/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#masonite) |
|
|
42
|
+
| [Morepath](https://morepath.readthedocs.io) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#morepath) |
|
|
43
|
+
| [Pyramid](https://trypyramid.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#pyramid) |
|
|
44
|
+
| [Quart](https://quart.palletsprojects.com/en/latest/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#quart) |
|
|
45
|
+
| [Responder](https://responder.kennethreitz.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#responder) |
|
|
46
|
+
| [Sanic](https://sanicframework.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#sanic) |
|
|
47
|
+
| [Starlette](https://www.starlette.io/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#starlette) |
|
|
48
|
+
| [Tornado](https://www.tornadoweb.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#tornado) |
|
|
49
|
+
| [TurboGears](https://turbogears.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#turbogears) |
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## **Features**
|
|
54
|
+
|
|
55
|
+
- 🔒 **Secure Headers**: Automatically apply headers like `Strict-Transport-Security`, `X-Frame-Options`, and more.
|
|
56
|
+
- 🛠️ **Customizable Policies**: Flexibly build your own security policies using method chaining.
|
|
57
|
+
- 🌐 **Framework Integration**: Compatible with various frameworks, ensuring cross-compatibility.
|
|
58
|
+
- 🚀 **No External Dependencies**: Lightweight and easy to include in any project.
|
|
59
|
+
- 🧩 **Easy to Use**: Integrate security headers in just a few lines of code.
|
|
60
|
+
- ⚡ **Asynchronous Support**: Async support for modern frameworks like **FastAPI** and **Starlette**.
|
|
61
|
+
- 📝 **Enhanced Type Hinting**: Complete type annotations for better developer experience.
|
|
62
|
+
- 📚 **Attribution to Trusted Sources**: Implements recommendations from MDN and OWASP.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## **Requirements**
|
|
67
|
+
|
|
68
|
+
- **Python 3.10** or higher
|
|
69
|
+
|
|
70
|
+
This library leverages modern Python features introduced in Python 3.10 and 3.11, such as:
|
|
71
|
+
|
|
72
|
+
- **Union Type Operator (`|`)**: Simplifies type annotations.
|
|
73
|
+
- **Structural Pattern Matching (`match` statement)**: Enhances control flow.
|
|
74
|
+
- **Improved Type Hinting and Annotations**: Provides better code clarity and maintenance.
|
|
75
|
+
- **`cached_property`**: Optimize memory usage and performance.
|
|
76
|
+
|
|
77
|
+
**Note:** If you're using an older version of Python (3.6 to 3.9), please use version **0.3.0** of this library, which maintains compatibility with those versions.
|
|
78
|
+
|
|
79
|
+
- **Dependencies**
|
|
80
|
+
|
|
81
|
+
This library has no external dependencies outside of the Python Standard Library.
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## **Installation**
|
|
86
|
+
|
|
87
|
+
You can install secure.py using pip, pipenv, or poetry:
|
|
88
|
+
|
|
89
|
+
**pip**:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
pip install secure
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
**Pipenv**:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
pipenv install secure
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
**Poetry**:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
poetry add secure
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## **Getting Started**
|
|
110
|
+
|
|
111
|
+
Once installed, you can quickly integrate `secure.py` into your project:
|
|
112
|
+
|
|
113
|
+
### Synchronous Usage
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
import secure
|
|
117
|
+
|
|
118
|
+
# Initialize secure headers with default settings
|
|
119
|
+
secure_headers = secure.Secure.with_default_headers()
|
|
120
|
+
|
|
121
|
+
# Apply the headers to your framework response object
|
|
122
|
+
secure_headers.set_headers(response)
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### Asynchronous Usage
|
|
126
|
+
|
|
127
|
+
For frameworks like **FastAPI** and **Starlette** that support asynchronous operations, use the async method:
|
|
128
|
+
|
|
129
|
+
```python
|
|
130
|
+
import secure
|
|
131
|
+
|
|
132
|
+
# Initialize secure headers with default settings
|
|
133
|
+
secure_headers = secure.Secure.with_default_headers()
|
|
134
|
+
|
|
135
|
+
# Apply the headers asynchronously to your framework response object
|
|
136
|
+
await secure_headers.set_headers_async(response)
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### **Example Usage**
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
import secure
|
|
143
|
+
|
|
144
|
+
# Create a Secure instance with default headers
|
|
145
|
+
secure_headers = secure.Secure.with_default_headers()
|
|
146
|
+
|
|
147
|
+
# Apply default secure headers to a response object
|
|
148
|
+
secure_headers.set_headers(response)
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## **Default Secure Headers**
|
|
154
|
+
|
|
155
|
+
By default, `secure.py` applies the following headers when using `with_default_headers()`:
|
|
156
|
+
|
|
157
|
+
```http
|
|
158
|
+
Cache-Control: no-store
|
|
159
|
+
Cross-Origin-Opener-Policy: same-origin
|
|
160
|
+
Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; object-src 'none'
|
|
161
|
+
Strict-Transport-Security: max-age=31536000
|
|
162
|
+
Permissions-Policy: geolocation=(), microphone=(), camera=()
|
|
163
|
+
Referrer-Policy: strict-origin-when-cross-origin
|
|
164
|
+
Server:
|
|
165
|
+
X-Content-Type-Options: nosniff
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## **Policy Builders**
|
|
171
|
+
|
|
172
|
+
`secure.py` allows you to customize headers such as **Content-Security-Policy** and **Permissions-Policy** with ease:
|
|
173
|
+
|
|
174
|
+
### **Content-Security-Policy Example**
|
|
175
|
+
|
|
176
|
+
```python
|
|
177
|
+
import secure
|
|
178
|
+
|
|
179
|
+
# Build a custom CSP policy
|
|
180
|
+
csp = (
|
|
181
|
+
secure.ContentSecurityPolicy()
|
|
182
|
+
.default_src("'self'")
|
|
183
|
+
.script_src("'self'", "cdn.example.com")
|
|
184
|
+
.style_src("'unsafe-inline'")
|
|
185
|
+
.img_src("'self'", "images.example.com")
|
|
186
|
+
.connect_src("'self'", "api.example.com")
|
|
187
|
+
)
|
|
188
|
+
|
|
189
|
+
# Apply it to secure headers
|
|
190
|
+
secure_headers = secure.Secure(csp=csp)
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
**Resulting HTTP headers:**
|
|
194
|
+
|
|
195
|
+
```http
|
|
196
|
+
Content-Security-Policy: default-src 'self'; script-src 'self' cdn.example.com; style-src 'unsafe-inline'; img-src 'self' images.example.com; connect-src 'self' api.example.com
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
### **Permissions-Policy Example**
|
|
200
|
+
|
|
201
|
+
```python
|
|
202
|
+
import secure
|
|
203
|
+
|
|
204
|
+
# Build a custom Permissions Policy
|
|
205
|
+
permissions = (
|
|
206
|
+
secure.PermissionsPolicy()
|
|
207
|
+
.geolocation("'self'")
|
|
208
|
+
.camera("'none'")
|
|
209
|
+
.microphone("'none'")
|
|
210
|
+
)
|
|
211
|
+
|
|
212
|
+
# Apply it to secure headers
|
|
213
|
+
secure_headers = secure.Secure(permissions=permissions)
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
**Resulting HTTP headers:**
|
|
217
|
+
|
|
218
|
+
```http
|
|
219
|
+
Permissions-Policy: geolocation=('self'), camera=('none'), microphone=('none')
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## **Framework Examples**
|
|
225
|
+
|
|
226
|
+
### **FastAPI**
|
|
227
|
+
|
|
228
|
+
```python
|
|
229
|
+
from fastapi import FastAPI
|
|
230
|
+
|
|
231
|
+
from secure import Secure
|
|
232
|
+
|
|
233
|
+
app = FastAPI()
|
|
234
|
+
secure_headers = Secure.with_default_headers()
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
@app.middleware("http")
|
|
238
|
+
async def add_security_headers(request, call_next):
|
|
239
|
+
response = await call_next(request)
|
|
240
|
+
await secure_headers.set_headers_async(response)
|
|
241
|
+
return response
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
@app.get("/")
|
|
245
|
+
def read_root():
|
|
246
|
+
return {"Hello": "World"}
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
### Flask
|
|
250
|
+
|
|
251
|
+
```python
|
|
252
|
+
from flask import Flask, Response
|
|
253
|
+
|
|
254
|
+
from secure import Secure
|
|
255
|
+
|
|
256
|
+
app = Flask(__name__)
|
|
257
|
+
secure_headers = Secure.with_default_headers()
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
@app.after_request
|
|
261
|
+
def add_security_headers(response: Response):
|
|
262
|
+
secure_headers.set_headers(response)
|
|
263
|
+
return response
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
@app.route("/")
|
|
267
|
+
def home():
|
|
268
|
+
return "Hello, world"
|
|
269
|
+
|
|
270
|
+
|
|
271
|
+
if __name__ == "__main__":
|
|
272
|
+
app.run()
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
---
|
|
276
|
+
|
|
277
|
+
## **Documentation**
|
|
278
|
+
|
|
279
|
+
For more details, including advanced configurations and integration examples, please visit the **[full documentation](https://github.com/TypeError/secure/tree/main/docs)**.
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
## **Attribution**
|
|
284
|
+
|
|
285
|
+
This library implements security recommendations from trusted sources:
|
|
286
|
+
|
|
287
|
+
- [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/))
|
|
288
|
+
- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/))
|
|
289
|
+
|
|
290
|
+
We have included attribution comments in the source code where appropriate.
|
|
291
|
+
|
|
292
|
+
---
|
|
293
|
+
|
|
294
|
+
## **Resources**
|
|
295
|
+
|
|
296
|
+
- [OWASP - Secure Headers Project](https://owasp.org/www-project-secure-headers/)
|
|
297
|
+
- [Mozilla Web Security Guidelines](https://infosec.mozilla.org/guidelines/web_security)
|
|
298
|
+
- [MDN Web Docs: Security Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#security)
|
|
299
|
+
- [web.dev: Security Best Practices](https://web.dev)
|
|
300
|
+
- [The World Wide Web Consortium (W3C)](https://www.w3.org)
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
### **License**
|
|
305
|
+
|
|
306
|
+
This project is licensed under the terms of the **[MIT License](https://opensource.org/licenses/MIT)**.
|
|
307
|
+
|
|
308
|
+
---
|
|
309
|
+
|
|
310
|
+
## **Contributing**
|
|
311
|
+
|
|
312
|
+
Contributions are welcome! If you'd like to contribute to `secure.py`, please feel free to open an issue or submit a pull request on **[GitHub](https://github.com/TypeError/secure)**.
|
|
313
|
+
|
|
314
|
+
---
|
|
315
|
+
|
|
316
|
+
## **Changelog**
|
|
317
|
+
|
|
318
|
+
For a detailed list of changes, please refer to the **[CHANGELOG](https://github.com/TypeError/secure/blob/main/CHANGELOG.md)**.
|
|
319
|
+
|
|
320
|
+
---
|
|
321
|
+
|
|
322
|
+
## **Acknowledgements**
|
|
323
|
+
|
|
324
|
+
We would like to thank the contributors of MDN Web Docs and OWASP Secure Headers Project for their invaluable resources and guidelines that help make the web a safer place.
|