victims-web 2.1.2

Victims Web Service

victims-web [](https://travis-ci.org/victims/victims-web)
===========
The victims web application.
## Report an Issue
If you find an issue with the service at http://victi.ms or the code, either
* Create a new issue at https://github.com/victims/victims-web/issues
* Email [e-mail]

## Contributing
If you have a patch or a feature that you want considered to be added to the project, feel free to send us a pull request.
Make sure you run pep8 before committing.
```sh
pep8 --repeat .
```

## Development
This is short guide on how to work on this code base using the provided `docker-compose` configuration and development `Dockerfile`. *Note* that the `Dockerfile` provided in the base directory is not to be used in production and is only for development use.

### Docker builds
#### Building the image
The image can be built to provide a working environment with all dependencies installed.
```sh
docker build -t local/victims-web .
```
#### Using the docker image
The docker image built as shown above will not contain the application source code but it expects the working directory to be mounted at `/opt/source`.
```sh
docker run --rm -it -v `pwd`:/opt/source local/victims-web
```

### Docker Compose
The `docker-compose.yml` file defines services required to run a working copy of the server on your local machine. Starting the server via `docker-compose` will;
1. start a supported version of MongoDB instance
2. seed the database with test data
3. start the web server using `python -m victims.web`
4. bind to port 5000 on your localhost

#### Starting a server
This will start an instance of the server as described above. Note that this is started with both `DEBUG` and `TESTING` enabled. This will also ensure that your code is auto re-loaded if changed.
```sh
docker-compose up server
```

#### Executing tests against your working copy
In order to execute tests against your working copy of code, you may use the `test` service as described in the `docker-compose.yml` file. This will start up dependant services, load seed data and then execute application tests and `pep8`.
```sh
docker-compose up test
```

## Usage
### Secured API Access
Submission endpoints like ```/service/submit/archive/java``` are secured by an implementation similar to what is used by AWS. The authentication token is expected in a HTTP header configured via the ```VICTIMS_API_HEADER``` configuration (default: ```X-Victims-Api```). If this is not present or if validation/authentication fails, then it falls back to *BASIC AUTH*.

An example using curl is as follows:
```sh
$ curl -v -X PUT -H "X-Victims-Api: $APIKEY:$SIGNATURE" -H "Date: Thu, 22 Aug 2013 15:20:37 GMT" -F archive=@$ARCHIVE https://$VICTIMS_SERVER/service/submit/archive/java?version=VID\&groupId=GID\&artifactId=AID\&cves=CVE-2013-0000,CVE-2013-0001
```

This can also be done using *BASIC-AUTH* as follows:
```sh
curl -v -u $USERNAME:$PASSWORD -X PUT -F archive=@$ARCHIVE_FILE https://$VICTIMS_SERVER/service/submit/archive/java?version=VID\&groupId=GID\&artifactId=AID\&cves=CVE-2013-0000,CVE-2013-0001
```

#### API Key and Client Secret Key
Each account on victi.ms is allocated an API Key and Secret key by default. This can be retrieved by visiting ```https://victi.ms/account```. These can be regenerated using the form at ```https://victi.ms/account_edit```.

#### Signature
The signature is generated using ```HTTP Method```, ```Path```, ```Date``` and the *MD5 hexdigest*.

_Notes:_
* The ```Path``` includes the query string parameters, e.g: ```/service/submit/archive/java?cves=CVE-0000-0000```
* The MD5 checksum includes the data (if available) of all files that are being submitted. The checksums are sorted in ascending order before adding to the string.
* The date is expected to be in ```GMT```. Eg: ```Thu, 22 Aug 2013 15:20:37 GMT```.

The following is a reference implementation in python:
```py
from hmac import HMAC

def generate_signature(secret, method, path, date, md5sums):
md5sums.sort()
ordered = [method, path, date] + md5sums
string = ''

for content in ordered:
if content is None:
raise ValueError('Required header not found')
string += str(content)

return HMAC(
key=bytes(secret),
msg=string.lower(),
digestmod=sha512
).hexdigest().upper()
```