rspec/rules/S6437/docker/rule.adoc

== Why is this an issue?

Sensitive data has been found in the Dockerfile or Docker image. The data
should be considered breached.

If malicious third parties can get a hold of such information, they could
impersonate legitimate identities within the organization. +
It is a clear breach of trust in the system, as the systems involved falsely 
assume that the authenticated entity is who it claims to be. +
The consequences can be catastrophic.

In Dockerfiles, secrets hard-coded, secrets passed through as variables or
created at build-time will cause security risks. The secret information can be
exposed either via the container environment itself, the image metadata or the
build environment logs.

Docker Buildkit's secret mount options should be used when secrets have to be
accessed at build time. For run-time secrets, best practices would recommend
only setting them at runtime, for example with the `--env` option of the docker
run command.

Note that files exposing the secrets should be securely stored and not exposed
to a large sphere. If possible, use a secret vault or another similar
component. For example, *Docker Swarm* provides a *secrets* service that can be
used to handle most confidential data.


=== Noncompliant code example

[source,docker]
----
FROM example
ARG PASSWORD
# Noncompliant
RUN wget --user=guest --password="$PASSWORD" https://example.com
----

=== Compliant solution

For build-time secrets, use https://docs.docker.com/engine/reference/builder/#run---mounttypesecret[Buildkit's secret mount type] instead:
[source,docker]
----
FROM example
RUN --mount=type=secret,id=build_secret \
    wget --user=guest --password=$(cat /run/secrets/build_secret) https://example.com
----

For runtime secrets, leave the environment variables empty until runtime:

[source,docker]
----
FROM example
ENV ACCESS_TOKEN=""
CMD /run.sh
----

Store the runtime secrets in an https://docs.docker.com/compose/env-file/[environment file] (such as `.env`) and then start the container with the https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file[`--env-file`] argument:

[source,docker]
----
docker run --env-file .env myImage
----

== Resources

* https://docs.docker.com/engine/reference/builder/#run---mounttypesecret[Dockerfile reference] - RUN command secrets mount points
* https://docs.docker.com/engine/swarm/secrets/[Docker documentation] - Manage sensitive data with Docker secrets
* https://cwe.mitre.org/data/definitions/522.html[MITRE, CWE-522] - Insufficiently Protected Credentials
* https://cwe.mitre.org/data/definitions/798.html[MITRE, CWE-798] - Use of Hard-coded Credentials


ifdef::env-github,rspecator-view[]
'''
== Implementation Specification
(visible only on this page)

=== Message
For secret generation:
* Change this code not to store a secret in the image.

For hardcoded secrets:
* Revoke and change this secret, as it might be compromised.

=== Highlighting

For literals and variable expansions:
* Highlight the command argument, whether a string literal or a variable expansion. If a variable, highlight as second location the ARG instruction.
For secret generation:
* Highlight the entire secret generation command

'''
endif::env-github,rspecator-view[]