Merge pull request #5 from cabinetoffice/newStructure

Add/ remove contents

source/docs/standards/software/architecture-decisions.html.md.erb → source/docs/architecture/architecture-decisions.html.md.erb

@@ -1,5 +1,5 @@
 ---
-title: Documenting architecture decisions
+title: Architecture decisions
 last_reviewed_on: 2024-05-10
 review_in: 12 months
 ---

source/docs/guidance/software-development-operations.html.md.erb

@@ -66,7 +66,7 @@ You should have security measures and monitoring for the application and infrast
 * Automate [access control tracking](./software/secrets-acl.html#content) and corresponding alerting
 * set up access and security related configuration change monitoring when appropriate
 * apply [principle of least privilege](./software/principle-least-access.html)
-* perform [threat modelling to anticipate security issues](./software/threat-modelling.html)
+* perform [threat modelling to anticipate security issues](https://intranet.cabinetoffice.gov.uk/it-data-and-security/cyber-and-information-security-services/threat-modelling/)
 * take extra precautions in [storing credentials](./software/storing-credentials.html)
 * [manage third party software dependencies](./software/tracking-dependencies.html)
 

source/docs/standards/software/docker.html.md.erb

@@ -0,0 +1,147 @@
+---
+title: Dockerfile guidance
+last_reviewed_on: 2024-01-05
+review_in: 6 months
+---
+
+# <%= current_page.data.title %>
+
+This style guide:
+
+* provides some conventions for creating production-ready Dockerfiles
+* supplements the official [Dockerfile reference](https://docs.docker.com/engine/reference/builder/)
+
+## Using tags and digests in FROM instructions
+
+The `FROM` instruction specifies the starting image for your Docker image build.
+
+A tag is a short label you can use to reference an image.
+
+For example:
+
+```
+FROM alpine:3.9
+```
+
+where:
+
+* `alpine` is the image name
+* `3.9` is the tag
+
+As you cannot rely on the tag pointing to the exact same image over time, you
+should instead use a digest, which identifies the image by a hash of its
+contents. This makes sure that you are always referencing the image that you
+expect.
+
+For example:
+
+```
+FROM alpine@sha256:769fddc7cc2f0a1c35abb2f91432e8beecf83916c421420e6a6da9f8975464b6
+```
+
+Where `sha256@769fddc7cc2f0a1c35abb2f91432e8beecf83916c421420e6a6da9f8975464b6`
+is the unique digest representing the particular variant of the image.
+
+To get the digest, run `docker pull <tag>`. For example:
+
+```
+$ docker pull alpine:3.9
+3.9: Pulling from library/alpine
+Digest: sha256:769fddc7cc2f0a1c35abb2f91432e8beecf83916c421420e6a6da9f8975464b6
+Status: Image is up-to-date for alpine:3.9
+```
+
+As [Dependabot](https://dependabot.com) has [support for updating `FROM` lines
+which use digests](https://github.com/dependabot/dependabot-core/pull/100),
+you can still use Dependabot to keep your images up-to-date.
+
+## Using multi-stage builds
+
+Using [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) enables the drastic
+reduction of image sizes, which in turn decreases the time taken to launch the container. There can be many stages
+within a Dockerfile. The result is a single layer image which discards the previous unrequired layers that were
+used in the compilation steps.
+
+As an example;
+
+```
+FROM golang:1.16 AS builder
+WORKDIR /go/src/github.com/alphagov/paas-aiven-broker/
+RUN git clone https://github.com/alphagov/paas-aiven-broker.git .
+RUN go mod download
+RUN go build
+
+FROM alpine:latest
+RUN apk --no-cache add ca-certificates
+WORKDIR /root/
+COPY --from=builder /go/src/github.com/alphagov/paas-aiven-broker/paas-aiven-broker .
+COPY --from=builder /go/src/github.com/alphagov/paas-aiven-broker/paas-aiven-broker/examples/config.json .
+CMD ["./paas-aiven-broker", "-config", "config.json"]
+```
+
+Building from this Dockerfile requires no changes to the existing build process e.g. `docker build -t myimage:latest .`
+
+It is also possible to stop the build at a specific stage using a command such as
+`docker build --target builder -t myimage:development .` which then enables running the container locally to debug the image.
+
+## Running programs as process ID (PID) 1
+
+The program running as PID 1 inside a container is responsible for:
+
+* cleaning up orphaned child processes
+* handling signals
+* returning the exit status from the container
+
+Most programs are unsuited to running as PID 1 inside a container. For
+example:
+
+* `bash` will not pass signals through to its children; for example, `SIGTERM` will
+  not lead to the container being shut down
+* `java` exits with an exit status of 143 when sent a SIGTERM, even if the application shuts
+  down cleanly
+* `node` does not reap orphaned child processes whose parent has exited
+
+[Tini](https://github.com/krallin/tini) provides a program suitable for
+running as PID 1 inside the container. You can use Tini to avoid the problems
+highlighted above. Tini is included by default with the Docker runtime or
+Alpine Linux images.
+
+You can use `tini` by passing the `--init` option to Docker when running your
+container or set Tini as the `ENTRYPOINT` for your container. For example:
+
+```
+ENTRYPOINT ["tini", "--"]
+```
+
+or for Java programs, to map an exit status of 143 to 0:
+
+```
+ENTRYPOINT ["tini", "-e", "143", "--"]
+```
+
+## Subshells
+
+The instructions `RUN`, `CMD` and `ENTRYPOINT` have 2 forms:
+
+* freeform text (for example `CMD “run -x”`)
+* an array-style (for example `CMD [“run”, “-x”]`)
+
+You should use the array-style syntax where possible.
+
+A Linux syscall will directly execute all commands specified using the
+array-style syntax, without an enclosing subshell. This process is more
+efficient and removes any ambiguity over how the commands will be interpreted.
+
+In the case of `ENTRYPOINT` or `CMD`, using the freeform text syntax means that
+a shell becomes PID 1 and most programs should not run as PID 1, as explained
+above.
+
+For more information about the special role of PID 1:
+
+* [avoid running NodeJS as PID 1 under Docker images](https://www.elastic.io/nodejs-as-pid-1-under-docker-images/)
+* [docker-node best practices - Handling Kernel Signals](https://github.com/nodejs/docker-node/blob/main/docs/BestPractices.md#handling-kernel-signals)
+* [Docker and the PID 1 zombie reaping problem](https://blog.phusion.nl/2015/01/20/docker-and-the-pid-1-zombie-reaping-problem/)
+
+## Links
+
+ * A smarter [Dockerfile linter](https://github.com/hadolint/hadolint) that helps you build best practice Docker images

source/docs/standards/software/principle-least-access.html.md.erb

@@ -44,7 +44,7 @@ It's important to recognise opportunities for privilege creep / accumulation and
 
 For human-readable secrets, such as a username and password, you should set up a separate secret or [password manager](https://www.ncsc.gov.uk/collection/passwords/password-manager-buyers-guide).
 
-If you’re using the gds-users account to log into your AWS accounts, you should assume a read-only role by default. You should only assume an admin role when absolutely necessary for a specific task. You should set up the admin account so that the session timeout is less than 12 hours. You should send the audit trail of admin access to the Cyber Security team. Use the Cyber Security Slack channel ([#cyber-security-help](https://gds.slack.com/archives/CCMPJKFDK)) to set up the audit trail.
+If you’re using the gds-users account to log into your AWS accounts, you should assume a read-only role by default. You should only assume an admin role when absolutely necessary for a specific task. You should set up the admin account so that the session timeout is less than 12 hours. You should send the audit trail of admin access to the Cyber Security team. Use the Cyber Security Slack channel ([#cyber-security][] to set up the audit trail.
 
 
 ## Further Guidance
@@ -54,3 +54,4 @@ If you’re using the gds-users account to log into your AWS accounts, you shoul
 - [NIST Special Publication 800-53 - AC-6 least privilege][polp]
 
 [polp]: https://csrc.nist.gov/Projects/risk-management/sp800-53-controls/release-search
+[#cyber-security]: https://intranet.cabinetoffice.gov.uk/it-data-and-security/cyber-and-information-security-services/