Skip to content

Commit 1db83b6

Browse files
pealtrufopealtrufo
authored
Merge pull request #113 from Santandersecurityresearch/develop
Added pypi documentation
2 parents 8b274bb + f8e6d84 commit 1db83b6

File tree

2 files changed

+144
-1
lines changed

2 files changed

+144
-1
lines changed

‎Pypi_description.md

+142
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
[![GitHub release](https://img.shields.io/github/release/Santandersecurityresearch/DrHeader.svg)](https://GitHub.com/Santandersecurityresearch/DrHeader/releases/)
2+
[![GitHub commits](https://img.shields.io/github/commits-since/Santandersecurityresearch/DrHeader/v1.2.1.svg)](https://GitHub.com/Santandersecurityresearch/DrHeader/commit/)
3+
[![Github all releases](https://img.shields.io/github/downloads/Santandersecurityresearch/DrHeader/total.svg)](https://GitHub.com/Santandersecurityresearch/DrHeader/releases/)
4+
[![HitCount](http://hits.dwyl.io/Santandersecurityresearch/DrHeader.svg)](http://hits.dwyl.io/Santandersecurityresearch/DrHeader)
5+
[![Total alerts](https://img.shields.io/lgtm/alerts/g/Santandersecurityresearch/DrHeader.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/Santandersecurityresearch/DrHeader/alerts/)
6+
[![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/Santandersecurityresearch/DrHeader.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/Santandersecurityresearch/DrHeader/context:python)
7+
[![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)
8+
9+
10+
# Welcome to drHEADer
11+
12+
There are a number of HTTP headers which enhance the security of a website when used. Often ignored, or unknown, these HTTP security headers help prevent common web application vulnerabilities when used.
13+
14+
DrHEADer helps with the audit of security headers received in response to a single request or a list of requests.
15+
16+
When combined with the OWASP [Application Security Verification Standard](https://github.com/OWASP/ASVS/blob/master/4.0/en/0x22-V14-Config.md) (ASVS) 4.0, it is a useful tool to include as part of an automated CI/CD pipeline which checks for missing HTTP headers.
17+
18+
# How Do I Install It?
19+
20+
This project was developed with Python 3.7.4.
21+
Whilst it works with Python 2.x, End of Life (EOL) is coming so if possible, use 3.x. The easiest way to install drHEADer is to clone this repository and via a terminal window, run the following command:
22+
23+
24+
``` console
25+
$ python3 setup.py install --user
26+
```
27+
This will install all the pre-requisites and you'll end up with a drheader executable.
28+
29+
30+
# How Do I Use It?
31+
32+
There are two ways you could use drHEADer, depending on what you want to achieve. The easiest way is using the CLI.
33+
34+
## CLI
35+
36+
drHEADer can perform a single scan against a target and report back which headers are present, like so:
37+
38+
``` console
39+
$ drheader scan single https://santander.co.uk
40+
```
41+
42+
If you wish to scan multiple sites, you'll need the targets in a JSON format, or a txt file, like so:
43+
44+
```
45+
[
46+
{
47+
"url": "https://example.com",
48+
"params": {
49+
"example_parameter_key": "example_parameter_value"
50+
}
51+
},
52+
...
53+
]
54+
```
55+
56+
For txt files, use the following command:
57+
58+
``` console
59+
$ drheader scan bulk -ff targets.txt
60+
```
61+
62+
There are a number of parameters you can specify during bulk scans, these are:
63+
| Option | Description |
64+
| :---------------- | :----------------------------------------------------- |
65+
| -p, --post | Use a post request to obtain headers |
66+
| --json | Output report as json |
67+
| --debug | Show error messages |
68+
| --rules FILENAME | Use custom rule set |
69+
| --rules-uri URL | Use custom rule set, to download from a remote server |
70+
| --merge | Merge custom rule set on top of default set |
71+
| --help | Show this message and exit |
72+
| --junit | Creates a junit report in `./reports/junit.xml` folder |
73+
74+
To save scan results, you can use the --json parameter and pipe it to [jq](https://stedolan.github.io/jq/), which is a lightweight and flexible command-line JSON processor,like so:
75+
76+
``` console
77+
$ drheader scan single https://santander.co.uk --json | jq '.'
78+
```
79+
80+
## In a Project
81+
82+
It is also possible to call drHEADer from within an existing project, and this is achieved like so:
83+
84+
from drheader import Drheader
85+
86+
# create drheader instance
87+
drheader_instance = Drheader(headers={'X-XSS-Protection': '1; mode=block'}, status_code=200)
88+
89+
report = drheader_instance.analyze()
90+
print(report)
91+
92+
### Customize HTTP method and headers
93+
94+
By default, the tool uses **GET** method when making a request, but you can change that by supplying the ```method``` argument like this:
95+
96+
# create drheader instance
97+
drheader_instance = Drheader(url="http://test.com", method="POST")
98+
99+
Remember you can use any method supported by ```requests``` such as POST, PUT, GET and DELETE.
100+
101+
At the same time, you can customize the headers sent by the request. For that, you just have to use the ```request_headers``` argument:
102+
103+
# create drheader instance
104+
custom_headers = {"token": "1234aerhga"}
105+
drheader_instance = Drheader(url="http://test.com", request_headers=custom_headers)
106+
107+
As we continue development on drHEADer, we will further enhance this functionality.
108+
109+
#### Other `requests` arguments
110+
111+
The _verify_ argument supported by ```requests``` can be included. The default value is set to `True`.
112+
113+
# create drheader instance
114+
drheader_instance = Drheader(url="http://test.com", verify=False)
115+
116+
Other arguments may be included in the future such as _timeout_, _allow_redirects_ or _proxies_.
117+
118+
# How Do I Customise drHEADer Rules?
119+
120+
DrHEADer relies on a yaml file that defines the policy it will use when auditing security headers. The file is located at `./drheader/rules.yml`, and you can customise it to fit your particular needs. Please follow this [link](RULES.md) if you want to know more.
121+
122+
# Notes
123+
124+
* On ubuntu systems you may need to install libyaml-dev to avoid errors related to a missing yaml.h.
125+
126+
## Roadmap
127+
128+
We have a lot of ideas for drHEADer, and will push often as a result. Some of the things you'll see shortly are:
129+
130+
* Building on the Python library to make it easier to embed in your own projects.
131+
* Releasing the API, which is seperate from the core library - the API allows you to hit URLs or endpoints at scale
132+
* Better integration into MiTM proxies.
133+
134+
# Who Is Behind It?
135+
136+
DrHEADer was developed by the Santander UK Security Engineering team, who are:
137+
138+
* David Albone
139+
* [Javier Domínguez Ruiz](https://github.com/javixeneize)
140+
* Fernando Cabrerizo
141+
* [James Morris](https://github.com/actuallyjamez)
142+

‎setup.py

+2-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
base_dir = os.path.dirname(__file__)
1111

1212

13-
with open(os.path.join(base_dir, "README.md")) as f:
13+
with open(os.path.join(base_dir, "Pypi_description.md")) as f:
1414
long_description = f.read()
1515

1616
with open('HISTORY.md') as history_file:
@@ -46,6 +46,7 @@
4646
install_requires=requirements,
4747

4848
description="DrHEADer helps with the audit of security headers received in response to a single request or a list of requests.",
49+
long_description_content_type='text/markdown',
4950
long_description=long_description,
5051
include_package_data=True,
5152
keywords='drheader',

0 commit comments

Comments
 (0)