pshtt, trustymail, and sslyze Scanner

Docker Image

This is a Docker container that uses
domain-scan to scan domains
using pshtt,
trustymail, and
sslyze.

This Docker container is intended to be run via
cisagov/orchestrator.

N.B.: The secrets in the src/secrets directory are only used
when testing via the docker-compose.yml composition. Normally this
Docker container is run via the Docker composition in
cisagov/orchestrator, which
expects the secrets in a different location.

Running

Running with Docker

To run the cisagov/scanner image via Docker:

docker run cisagov/scanner:1.4.0

Running with Docker Compose

Create a compose.yml file similar to the one below to use Docker Compose.

---
name: scanner

services:
  scanner:
    image: cisagov/scanner:1.4.0
    volumes:
      - type: bind
        source: <your_log_dir>
        target: /home/cisa/shared

Start the container and detach:
```
docker compose up --detach
```

Using secrets with your container

This container also supports passing sensitive values via Docker
secrets. Passing sensitive
values like your credentials can be more secure using secrets than using
environment variables. See the
secrets section below for a table of all supported secret files.

To use secrets, create an aws_config file in this
format:

[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
region=us-east-1
output=json

Then add the secret to your compose.yml file:

---
name: scanner

secrets:
  aws_config:
    file: ./secrets/aws_config

services:
  scanner:
    image: cisagov/scanner:1.4.0
    volumes:
      - type: bind
        source: <your_log_dir>
        target: /home/cisa/shared
    secrets:
      - source: aws_config
        target: aws_config

Updating your container

Docker Compose

Pull the new image from Docker Hub:
```
docker compose pull
```
Recreate the running container by following the previous instructions:
```
docker compose up --detach
```

Docker

Stop the running container:
```
docker stop <container_id>
```
Pull the new image:
```
docker pull cisagov/scanner:1.4.0
```
Recreate and run the container by following the previous instructions.

Updating Python dependencies

This image uses Pipenv to manage Python dependencies using a Pipfile.
Both updating dependencies and changing the Pipenv configuration in src/Pipfile
will result in a modified src/Pipfile.lock file that should be committed to the
repository.

Warning

The src/Pipfile.lock as generated will fail pre-commit checks due to JSON formatting.

Updating dependencies

If you want to update existing dependencies you would run the following command
in the src/ subdirectory:

pipenv lock

Modifying dependencies

If you want to add or remove dependencies you would update the src/Pipfile file
and then update dependencies as you would above.

Note

You should only specify packages that are direct requirements of
your Docker configuration. Allow Pipenv to manage the dependencies
of the specified packages.

Image tags

The images of this container are tagged with semantic
versions of the underlying example project that they
containerize. It is recommended that most users use a version tag (e.g.
:1.4.0).

Image:tag	Description
`cisagov/scanner:1.4.0`	An exact release version.
`cisagov/scanner:1.3`	The most recent release matching the major and minor version numbers.
`cisagov/scanner:1`	The most recent release matching the major version number.
`cisagov/scanner:edge`	The most recent image built from a merge into the `develop` branch of this repository.
`cisagov/scanner:nightly`	A nightly build of the `develop` branch of this repository.
`cisagov/scanner:latest`	The most recent release image pushed to a container registry. Pulling an image using the `:latest` tag should be avoided.

See the tags tab on Docker
Hub for a list of all the supported tags.

Volumes

Mount point	Purpose
`/home/cisa/shared`	Output

Ports

There are no ports exposed by this container.

Environment variables

Required

There are no required environment variables.

Optional

Name	Purpose	Default
`AWS_CONFIG_FILE`	The path to the configuration file containing the AWS credentials.	`null`
`AWS_PROFILE`	The AWS profile to use.	`null`

Secrets

Filename	Purpose
aws_config	AWS credentials allowing read-only access to the Elasticsearch DMARC database in this format

Building from source

Build the image locally using this git repository as the build context:

docker build \
  --tag cisagov/scanner:1.4.0 \
  https://github.com/cisagov/scanner.git#develop

Cross-platform builds

To create images that are compatible with other platforms, you can use the
buildx feature of
Docker:

Copy the project to your machine using the Code button above
or the command line:
```
git clone https://github.com/cisagov/scanner.git
cd scanner
```
Create the Dockerfile-x file with buildx platform support:
```
./buildx-dockerfile.sh
```

Build the image using buildx:

docker buildx build \
  --file Dockerfile-x \
  --platform linux/amd64 \
  --output type=docker \
  --tag cisagov/scanner:1.4.0 .

Contributing

We welcome contributions! Please see CONTRIBUTING.md for
details.

License

This project is in the worldwide public domain.

This project is in the public domain within the United States, and
copyright and related rights in the work worldwide are waived through
the CC0 1.0 Universal public domain
dedication.

All contributions to this project will be released under the CC0
dedication. By submitting a pull request, you are agreeing to comply
with this waiver of copyright interest.

cisagov/scanner