hmpps-electronic-monitoring-datastore-api

Contents

• About this project
• Project set up
• Running the application locally
  • Running the application in intellij
  • Running the application with connection to Athena
  • Running the application with mocked Athena

About this project

An API used by the Electronic Monitoring datastore UI, a service that allows users to interrogate the electronic monitoring datastore hosted in the HMPPS Modernisation Platform.

It is built using Spring Boot and Kotlin as well as the following technologies for its infrastructure:

• AWS - Services utilise AWS features through Cloud Platform.
• Cloud Platform - Ministry of Justice's (MOJ) cloud hosting platform built on top of AWS which offers numerous tools such as logging, monitoring and alerting for our services.
• Docker - The API is built into docker images which are deployed to our containers.
• Kubernetes - Creates 'pods' to host our environment. Manages auto-scaling, load balancing and networking to our application.

Project set up

Enable pre-commit hooks for formatting and linting code with the following command;

./gradlew addKtlintFormatGitPreCommitHook addKtlintCheckGitPreCommitHook

Running the application locally

The application comes with a local spring profile that includes default settings for running locally.

There is also a docker-compose.yml that can be used to run a local instance in docker and also an instance of HMPPS Auth.

docker compose pull && docker compose up

will build the application and run it and HMPPS Auth within a local docker instance.

Running the application in Intellij

docker compose pull && docker compose up --scale hmpps-electronic-monitoring-datastore-api=0

will just start a docker instance of HMPPS Auth. The application should then be started with a local active profile in Intellij.

Connecting to the cloud platform kubernetes cluster

Configure KubeCtl to let you connect to the Cloud Platform Kubernetes cluster - follow this guide

Running the application with connection to dev Athena

When deployed to cloud-platform, the pod running the service is configured to use a service account which gives it the permissions of the linked IAM role. The linked IAM role is allowed to assume a role that gives it access to the Electronic Monitoring Datastore (Athena). When we're running the application locally, we want to try to connect to AWS/Athena in a similar way to the deployed service. To achieve this, we can get a programmatic access key which will give our workstation access to AWS.

Navigate to https://moj.awsapps.com/start/#/?tab=accounts and retrieve access keys for electronic-monitoring-data-test. Add these to the .env file in root of this project. N.B. These will expire so you will need to refresh them periodically.

e.g.

AWS_ACCESS_KEY_ID="ASIAIOSFODNN7EXAMPLE"
AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
AWS_SESSION_TOKEN="IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE"

These credentials will allow access to Athena without any additional configuration, however, the goal is to connect to Athena in a similar way the deployed service will, so we will also configure a role to assume. The ./scripts/get-athena-credentials.sh script will fetch the ARN of the role the dev environment will use to connect to Athena. Add this to your .env file.

e.g.

ATHENA_GENERAL_IAM_ROLE=""

Running tests

When we run tests either via the command line or IntelliJ, the AWS SDK still expects to find credentials from any of the default credential providers.

The easiest way to get around this is to add some dummy variables to the AWS credentials file ~/.aws/credentials. This should allow you to run any test in IntelliJ or from the cli e.g. ./gradlew check.

AWS_ACCESS_KEY_ID="ASIAIOSFODNN7EXAMPLE"
AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
AWS_SESSION_TOKEN="IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE"

Code coverage

This project has Jacoco integrated and this will run after each test run. The generated report can be found here and can be opened in your browser.

Vulnerability analysis

Gradle includes OWASP dependency checking. Run this locally using:

1. ./gradlew dependencyCheckUpdate --info to update the definitions file
2. ./gradlew dependencyCheckAnalyze --info to run the check. The results will be found in ./build/reports/dependency-check-report.html

To run trivy analysis on the built image locally, run:

1. docker compose build to build the image
2. brew install aquasecurity/trivy/trivy to install trivy
3. trivy image <your image uid> to scan.