Security HQ
Centralised security information for AWS accounts.
Security HQ webapp
This webapp presents the primary interface for Security HQ.
The watched-account
CloudFormation template will create ConfigRules
that monitor the status of other AWS accounts. This application
presents the data collected by those processes.
It also provides an interface on some markers of a watched AWS account's health from a security point of view.
Development
Getting started
There are lots of good Java version managers, but we recommend
asdf here. Once installed, it will respect the
.tools-versions
file in the root of the repository to ensure you are using the
same Java version (11) and distribution (Corretto) as prod.
AWS Configuration
Note: this section is only necessary if you do not already have another means of accessing your account(s) with the required permissions. Particularly, that is true for Guardian developers, who can use temporary credentials from Janus in the usual way.
The security-test-user CloudFormation template should create a user with all the required permissions.
Once the CloudFormation is complete and the user created, you will need to create an access key for this user.
In the console, select the user and then under security credentials
click create access key
.
You will be presented with an Access key ID and a Secret access key that you are going to use during the next step.
Create the file ~/.aws/credentials
with the following contents
[security-test]
aws_access_key_id = <Access key ID>
aws_secret_access_key = <Secret Access key>
If you already had this file, you should just add this section.
Create the entry below in ~/.aws/config
file.
[profile security-test]
region = eu-west-1
Other Configuration
There are two other files that you will need to run security HQ locally. These are:
~/.gu/security-hq.local.conf
~/.gu/security-hq-service-account-cert.json
Both of these files can be found in the Security AWS account in S3 here s3://security-dist/security/DEV/security-hq/
.
To access the Security AWS account you will need to raise a PR in Janus
to get access to the Security account (Security.dev
should be appropriate).
Once you have Janus credentials for the AWS Security account, you can copy the files from S3 by using the following:
aws s3 cp s3://security-dist/security/DEV/security-hq/security-hq.local.conf ~/.gu --profile security
aws s3 cp s3://security-dist/security/DEV/security-hq/security-hq-service-account-cert.json ~/.gu --profile security
You will then need to update ~/.gu/security-hq.local.conf
as follows:
# Update this path to reference your home directory
GOOGLE_SERVICE_ACCOUNT_CERT_PATH="/Users/ADD_YOUR_NAME/.gu/security-hq-service-account-cert.json"
Adding additional AWS accounts for local development
When running security HQ locally, you can modify the list of AWS accounts to include additional account. For example, you may want to add a specific account for debugging purposes. You will need valid AWS credentials for any accounts you wish to include.
It's really easy to add a new AWS account! Go to ~/.gu/security-hq.local.conf
,
add a new object to the AWS_ACCOUNTS
list, like this Deploy Tools account example:
AWS_ACCOUNTS = [
{
name = "Deploy Tools"
id = "deployTools"
roleArn = ""
}
]
The value of id
should be the same as the AWS Profile name, which you can see when you copy your credentials from Janus. You can add a roleArn
if you want to generate an IAM report, otherwise you don't need it.
AWS Security Policies
See watched-account
template under cloudformation
folder for the security policies needed to run security-hq.
nginx setup
When running security-hq locally you will always need nginx running in the background. You only need to configure dev-nginx once (as described in step 2), but if you restart your computer, you will need to run sudo nginx
to restart the nginx process.
To check nginx is running, you can run ps -e | grep nginx
and you should receive a response that includes nginx: master process nginx
and nginx: worker process
.
- Install dev-nginx:
dev-nginx contains a number of generic useful scripts to:
- issue certs locally (and automatically trust them)
- generate an nginx config file from a yaml definition
MacOS users:
brew tap guardian/homebrew-devtools
brew install guardian/devtools/dev-nginx
There are further instructions in the dev-nginx repo.
- configure dev-nginx:
run each of these commands:
dev-nginx add-to-hosts-file security-hq.local.dev-gutools.co.uk
dev-nginx setup-cert security-hq.local.dev-gutools.co.uk
dev-nginx setup-app nginx/nginx-mapping.yml
- To stop and restart nginx you can now run:
dev-nginx restart-nginx
- Now when you run the project (see next step for details), it will also be accessible via https://security-hq.local.dev-gutools.co.uk/
DynamoDB local setup
Running Security HQ locally requires a local instance of DynamoDb to connect
to. The run
tasks handles most of the work automatically by starting and
stopping DynamoDBLocal
as appropriate. It does not, however, create a table
for the application to use.
To do that, the following script needs to be executed while the application is running. This only needs to be done once, as the database is stored on disk and persistent between application runs.
$ ./script/setup
Running project
From the root of the project:
-
Get Security Janus credentials.
-
Ensure you are running Java 11
-
Run sbt:
$ ./sbt
(you must use this script to start SBT as it loads the local config copied from S3 in the previous steps). -
Select the project that you want to run:
sbt:security-hq> project hq
-
Start the application:
sbt:security-hq> run
Once the server has started, the webapp is accessible at https://security-hq.local.dev-gutools.co.uk/
Working with CSS and JS
Security HQ uses Prettier and ESLint to provide opinionated code formatting and linting. As part of the automated build, all CSS and JS will be validated using the rules of Prettier and ESLint.
Testing changes, and passing code validation
Before beginning, you may want to install a node version manager, such as nvm.
-
You will need to install Yarn to handle the project dependencies:
- Linux: Instructions can be found here: https://yarnpkg.com/lang/en/docs/install/#linux-tab
- Mac OSX:
$ brew install yarn
-
Then install all the dependencies by running:
$ yarn
Running checks with Yarn
To see any errors and warnings for the CSS use:
$ yarn run sass-lint
To see any errors and warnings for the JS use:
$ yarn run eslint
To attempt to auto-fix the CSS and JS, you can try using Prettier:
$ yarn run prettier
N.B. Although Prettier will write to the files, changes will still need to be staged afterwards.
Checking CloudFormation
The aws cli can perform some basic template validation.
It requires AWS credentials to run, and can validate a single file like so:
aws cloudformation validate-template --template-body file:///${PWD}/cloudformation/security-test-user.yaml --profile <AWS_PROFILE>
CFN nag is a linting tool for CloudFormation templates that can help catch security issues.
If you have it installed, you can run:
cfn_nag_scan --input-path cloudformation/*
Dependabot
This repo has [dependabot security updates enabled])(https://github.com/guardian/security-hq/security/dependabot), which means dependabot will open PRs to fix security vulnerabilities in JS prod and dev dependencies. Note that this is different from the dependabot dependency updates feature, which auto-updates all dependencies to their latest versions, which this repo does not have enabled.
The dependabot PRs are built as usual, except for the fact that the builds are not uploaded to riff raff. This is due to them not having access to the repo secrets. If you'd like to deploy a dependabot PR to test before merging, you'll need to manually trigger a build yourself. This will provide the build environment access to the necessary secrets.
Introduction to Security HQ's features
Credentials Reaper
The Credentials Reaper is a feature in Security HQ which automatically disables permanent IAM users with access keys that haven’t been rotated within 90 days for users with a password (human users) or 365 days for users without a password (machine users). It also disables permanent users who have left the Guardian.
The reaper sends email notifications to the AWS account the user is in, before disabling a user. The emails are sent via Anghammarad and uses it's AWS Account to email address mappings.
You can also find the dynamo table in the Security AWS Account.
Lambda
Security HQ holds a Lambda, which checks for security groups that are open to the world, except ELB groups. This data is used for https://security-hq.gutools.co.uk/security-groups
.
It is deployed as a stack set and is defined in cloudformation/watched-account.template.yaml
.
This lambda is deployed manually by creating a JAR file locally and uploading it to S3: s3://guardian-dist/guardian/PROD/securitygroups-lambda/
. The version name is important, because
the cloudformation has a paramter, version
, which is used to locate the correct S3 file. The stackset is then deployed manually again to all accounts from the root account.
The build and deploy process is manual at present. The lambda was deployed once in 2018 and hasn't been updated since. Health tickets have been put onto the backlog to try to improve this process.