Account Interventions Service

Introduction

A serverless typescript project for the Account Intervention Service solution.

How To

Prerequisites

• Docker >= v20.10
• SAM CLI >= 1.138.0

Clone the repo

git clone git@github.com:govuk-one-login/account-interventions-service.git
cd account-interventions-service

Setup Pre-Commit

pre-commit install -f

Setup access to private repositories

In order to install private packages, such as @govuk-one-login/event-catalog, an npmrc file is required. This ~/.npmrc file must contain a Personal Access Token (PAT) with read:packages permissions in the following format:

@govuk-one-login:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<generated-token>

For guidance on generating a PAT, refer to the documentation: Configuring Node package managers and Managing Your Personal Access Tokens.

Install Project Dependencies

$ npm install

Test Project

To fully test the application, try the test command below

$ npm test

Run mutation tests

We have Stryker installed on the project for mutation testing. You can run Stryker via npm script:

npm run test:mutation

or manually:

npx stryker run

These commands are equivalent and running either will run the mutation tests, then produce an html report in the /reports directory. This report can be opened in the browser and shows where in the code the mutation tests failed, i.e. where Stryker made meaningful changes to the code and the tests still passed.

Build & deploy main application manually stack for development

To build the application code and deploy the ais-main stack use the following commands from project root directory. Make sure NOT to pass a --template / -t flag to the sam deploy command. By simply running sam deploy --guided SAM will pick up the relevant version of the main template from the default directory .aws-sam/build which is created during the build process Ensure you have logged into AWS and obtained credentials before attempting to deploy manually

$ npm run package
$ sam deploy --guided

Deploy alarm stack manually for development

To manually deploy the ais-alarm stack, use the following commands from project root directory. Ensure you have logged into AWS and obtained credentials before attempting to deploy manually.

$ sam deploy --guided -t src/infra/alarm/template.yaml

Deploy core stack manually for development

To manually deploy the ais-core stack, use the following commands from project root directory. Ensure you have logged into AWS and obtained credentials before attempting to deploy manually.

$ sam deploy --guided -t src/infra/core/template.yaml

Lints Code, SAM Template & Open API Spec

$ npm run lint

• npm run lint:code - TypeScript is linted by ESLint
• npm run lint:iac - SAM template is linted by SAM CLI
• npm run lint:spec:oas - OpenAPI specification is linted by Spectral

Fix ES Lint Issues

$ npm run lint:code:fix

Check For Vulnerable Dependencies

$ npm audit

Fix Vulnerable Dependencies

Architecture Diagram

How To Deploy

1. Setup Base CloudFormation Stacks

To deploy the base common CloudFormation stacks required created by Dev Platform prior to deploying the solution use the Stack Orchestation tool provided in our stack-orchestration directory and run the production_bootstrap.sh script.

The stacks to be deployed are:

1. alerting-integration
2. api-gateway-logs
3. certificate-expiry
4. vpc
5. lambda-audit-hook
6. infra-audit-hook

Setup AWS SSO Login

$ aws configure sso

• Choose session name: {enter your name}
• Accept authorisation in browser
• Choose the AWS account in the dropdown
• CLI default client Region: eu-west-2
• CLI default output format: json
• aws sso login --profile _{profile name provided for account}

Stack Orchestation Tool Prerequisites

• aws-vault
• jq

⚡ Prior to deploying check the latest versions of these stacks are being referenced which can be found here > CHANGELOG

Steps:

$ cd stack-orchestation
$ aws configure sso
$ aws sso login --profile di-account-intervention-admin-324281879537
$ sh production_bootstrap.sh

The bootstrap script should deploy all base Cloudformation stacks required for account set up.

2. Deploy ais-infra stacks

Clone the ais-infra repo

git clone git@github.com:govuk-one-login/ais-infra.git
cd ais-infra

⚠️ Setup pre-commit

$ pre-commit install -f

Deploy the following stacks in the following order:

1. ais-infra-alerting - README.md
2. ais-infra-common - README.md
3. ais-dynatrace-metrics - README.md

3. Setup secure pipelines

These pipelines should deploy the main solution stacks

1. ais-core-pipeline deploy our ais-core stack
2. ais-main-pipeline deploys our ais-main stack
3. ais-alarm-pipeline deploys our ais-alarm stack

Setup these 3 secure pipelines by using the Stack Orchestation tool provided in our Stack-Orchestration directory and run the production_pipelines.sh script.

⚡ Prior to deploying check the latest version of secure pipelines is being referenced in the production_pipelines.sh script > CHANGELOG

Deployment Steps:

$ cd stack-orchestation
$ aws configure sso
$ aws sso login --profile di-account-intervention-admin-324281879537
$ sh production_pipelines.sh

Once all production pipelines have been set up, proceed to running the staging_pipelines.sh script to allow promotion up to production account.

$ cd stack-orchestation
$ aws configure sso
$ aws sso login --profile di-id-reuse-core-staging-admin-922902741880
$ sh staging_pipelines.sh

Stack Deployment Versions

❗ Update this table if version has been updated

	ais-main-pipeline	ais-core-pipeline	ais-alarm-pipeline	alerting-integration	api-gateway-logs	certificate-expiry	vpc	ecr-image-scan-findings-logger	lambda-audit-hook	infra-audit-hook
Dev	v2.48.0	v2.48.0	v2.48.0	v1.0.6	v1.0.5	v1.1.0	v2.3.1	v.1.1.4	n/a	n/a
Build	v2.48.0	v2.48.0	v2.48.0	v1.0.6	v1.0.5	v1.1.0	v2.3.1	v.1.1.4	n/a	n/a
Staging	v2.48.0	v2.48.0	v2.48.0	v1.0.6	v1.0.5	v1.1.0	v2.3.1	v.1.1.4	n/a	n/a
Integration	v2.48.0	v2.48.0	v2.48.0	v1.0.6	v1.0.5	v1.1.0	v2.3.1	v.1.1.4	n/a	n/a
Production	v2.48.0	v2.48.0	v2.48.0	v1.0.6	v1.0.5	v1.1.0	v2.3.1	n/a	n/a	n/a

Additional Info

Old SAM version

If you already have an earlier version of SAM installed you may need to either upgrade SAM or uninstall it and reinstall it. Here are some instructions you can follow to do this:

$ brew upgrade aws-sam-cli

Managing AWS SAM CLI versions - AWS Serverless Application Model

Pre-commit

The command may be required if you do not already have pre-commit installed on your machine

$ brew install pre-commit

Using nodenv

If you work across multiple Node.js projects there's a good chance they require different Node.js and npm versions.

To enable this we use nodenv to switch between versions automatically.

1. Install and setup nodenv.
2. Install the NodeJS version used by this project nodenv install <node-version>.

$ brew install nodenv
$ nodenv init
$ cat .node-version | nodenv install

Getting latest releases of Node Version supported by nodenv (this may take a while)

brew upgrade nodenv node-build

Testing the Private Api Gateway endpoint

The api in this application is a private api, which means testing it can't be done using tools like postman. The lambda {stack-name}-InvokePrivateAPIGatewayFunction has been created to allow the api to be tested. Since this lambda is created within the application's VPC, it meets the required security measures so it is able to successfully invoke the endpoint.

The api has the following format:

<baseurl>/ais/:userId?history=true

Note: the query string parameter (history=true) is optional.

This lambda sets default values for the baseUrl and the endpoint (e.g. ais) in the environment variables.

There are two ways to use this lambda:

📆 Using the lambda event:

All of these keys are optional. Anything provided in the event will override the default value in the environment variable.

{
    "userId": "<theUserId>",
    "queryParameters": "history=true",
    "baseUrl": "<theBaseUrl eg http://hello-world.com>",
    "endpoint": "<theEndpoint eg /ais>",
    "headers": { 'Content-Type': 'application/json' } // add any headers here
}

🌱 Using the environment variables:

Update the values for these variables. Note, if you also provide the equivalent value in the lambda event, the lambda will use the lambda event values.

USER_ID
QUERY_PARAMETERS
BASE_URL
END_POINT

Note: that at the moment the lambda is not set up to work for a post request, so changes to the lambda will need to be made if post requests become a requirement.