Skip to content

Latest commit

 

History

History
376 lines (248 loc) · 14.7 KB

HowTo.md

File metadata and controls

376 lines (248 loc) · 14.7 KB
Raw

HowTo

View this page in Japanese (日本語)| Back to Repository README

Here we will describe howTo for various settings.

VisualStudioCode Setup Instructions

The choice of a text editor is optional, but this section describes the setup steps for using VSCode. If you use another text editor, we strongly recommend that you use one that can work with the following tools:

NOTE:

Code completion, jumping to definitions, and so on are implemented by VSCode's built-in features. If you want to use the equivalent functionality in another text editor, consider using a text editor or its plugin support Language Server Protocol (LSP).

Installing and Initializing VSCode

Please install from Visual Studio Code

For macOS, select Running Visual Studio Code on macOS so you can use code command to be executed from the shell. It is set automatically on Windows.

Installing the VSCode Extension

If you clone this repository in a subsequent step and open it in VSCode, you will be prompted to install the recommended extension. Now click on Install.

vscode-recommended-extensions

This recommended extension is defined in .vscode/extensions.json. For more information about this feature, see Managing Extensions in Visual Studio Code.

Configuring the VSCode Extension

Press Ctrl + Shift + p (macOS: Command + Shift + p) to display the Command Palette and Preferences:Open Select Settings (JSON) Add the following settings: This will allow the code to be linted, formatting, etc. at the time of saving.

    "editor.codeActionsOnSave": {
        "source.fixAll.eslint": true
    },
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true,
    "prettier.useEditorConfig": true,

Git pre-commit hook setup

Setting up simple-git-hooks

Run the following command in the top directory of the BLEA source code:

# in the top directory of BLEA
npx simple-git-hooks

Git hooks are set up (.git/hooks/pre-commit) so that lint-staged runs before committing.

Installing and Configuring Git-Secrets

lint-staged is configured to perform checks by git-secrets in addition to eslint and prettier checks (package.json).

Install awslabs/git-secrets - GitHub according to the README Please Then run the following command to work with the git command:

git secrets --register-aws --global

Next, register a list of credentials that are allowed as dummy values. Edit ~/.gitconfig and look for the [secrets] section generated by the above command and add the following: These are the account IDs that you are using as dummies in the source code of BLEA.

    # Fictitious AWS Account ID
    allowed = 111122223333
    allowed = 444455556666
    allowed = 123456789012
    allowed = 777788889999
    allowed = 000000000000
    allowed = 111111111111
    allowed = 222222222222
    allowed = 333333333333

NOTE

Do not run git secrets install. In this project, simple-git-hooks is used to hook pre-commit and call git-secrets from here. Running git secrets install causes hook conflicts.

Skip Deployment Approvals and Don't Roll Back

You can control deployment behavior by specifying options in the cdk command. Here are some useful settings that are often used.

Skip approval when deploying

Normally, when deploying with a CDK, you will be prompted for approval, but specify the -—require-approval never option on the cdk command line This will prevent the confirmation prompt from being displayed (but be careful!).

Do not roll back if deployment fails

The CDK deploys using CloudFormation, but typically if an error occurs during deployment, the target stack is rolled back to the state it was in before the deployment started. If you specify the -R or -—no-rollback option on the cdk command line, the deployment process will not be rolled back when a deployment error occurs. Stops If you fix the error and deploy it again, the process will resume from the point where it stopped. This is useful for trial-and-error settings.

How to set cdk.json

By setting RequireApproval and Rollback to cdk.json as follows, you do not need to set each time in the command.

{
  "app": "npx ts-node --prefer-ts-exts bin/blea-guest-ecs-app-sample.ts",
  "requireApproval": "never",
  "rollback": false,

Set up Slack for AWS ChatBot

To send alarms to Slack, deploy the Blea-ChatbotSecurity and Blea-ChatbotMonitor stack. Before you can deploy these stacks, you must set up a chat client for AWS Chatbot. If you do not do this, the stack deployment will fail. The steps to configure AWS Chatbot are as follows:

1. Create a workspace and channel in Slack

(This step is for Slack.) Create a workspace and create a Slack channel where you want to receive messages. Make a note of the Slack channel ID (you can copy the channel ID by right-clicking on the channel name and selecting “Copy Link”). This link looks like this: https://your-work-space.slack.com/archives/C01XXXXXXXX. where C01XXXXXXXX The channel ID of that channel.

2. Set up a chat client with AWS Chatbot

Create a Slack workspace on AWS Chatbot by following steps 1-3 in Setting up AWS Chatbot with Slack in the following procedure Please

Make a note of the ID of the Workspace you created. It looks like T8XXXXXXX.

Note

If you configure a private Slack channel, run the /invite @AWS command in Slack to invite the AWS Chatbot to the chat room.

3. Set the workspace ID and channel ID in the parameter file (parameter.ts)

Set the Slack workspace ID and channel ID in the parameter file (parameter.ts) for each use case as follows. Please specify different channels for security and monitoring:

For security (governance base):

export const devParameter: AppParameter = {
  // ...
  securitySlackWorkspaceId: 'T8XXXXXXX',
  securitySlackChannelId: 'C00XXXXXXXX',
  // ...
};

For monitoring (sample application):

export const devParameter: AppParameter = {
  // ...
  monitoringSlackWorkspaceId: 'T8XXXXXXX',
  monitoringSlackChannelId: 'C00XXXXXYYY',
  // ...
Setting Item Value Retrieval Source
securitySlackWorkspaceID Workspace ID: Copy from Workspace Details in AWS Chatbot - for security alarms
securitySlackChannelID Retrieved from the target channel link in the Slack App - for security alarms
MonitoringSlack WorkspaceID Workspace ID: Copied from AWS Chatbot Workspace Details - for monitoring alarms (you'll usually use the same workspace for security)
MonitoringSlack ChannelID Retrieved from the target channel link in the Slack App - for monitoring alarms

Deployment with CloudShell

You can use CloudShell to deploy this template from the management console. However, keep in mind that ClouShell deletes data from the environment you set up after 120 days of inuse.

see: https://docs.aws.amazon.com/cloudshell/latest/userguide/limits.html

1. Start CloudShell

  • Launch CloudShell by clicking the [>_] icon in the AWS Management Console (next to your account name in the top right corner of the screen) OpenConsole

2. Set up the CDK execution environment

See: https://docs.aws.amazon.com/ja_jp/cdk/latest/guide/getting_started.html

  • Update npm
sudo npm -g install npm

3. Upload CDK code

  1. Download the CDK code to be deployed and archive it with zip, etc.

  2. From the CloudShell screen, click [Action]-[Upload File] to upload the archived file UploadFiles

  3. Extract uploaded files

  • If you have access to a remote repository, you can also use CloudShell to git clone to get CDK code

4. Build and deploy

cd path/to/source
npm ci
# in the usecase directory which you want to deploy
cd usecases/blea-uest-serverless-api-sample
npx aws-cdk deploy --all --profile prof_dev

Update package dependencies

If you want to use the latest CDK, you must update the dependent NPM packages. The procedure for updating is as follows: This is done in the top directory of BLEA.

# in the top directory of BLEA
npm update --workspaces

NOTE

If a dependency package version inconsistency occurs here, fix package.json accordingly. For example, jest is listed as devDependencies in package.json because it is used as a testing tool for this project. aws-cdk also depends on jest, and aws-cdk is the version of jest listed in package.json by ncu -u There is a possibility that it will no longer match the version required by.

Development process

After checking out the code, the flow for editing, building, and deploying the CDK code is as follows.

1. Check out the code and install the required libraries

git clone https://github.com/aws-samples/baseline-environment-on-aws.git
cd baseline-environment-on-aws
npm ci

2. Deploy, modify, and test a single use case

cd usecases/blea-guest-web-app-sample

# Check the differences
npx aws-cdk diff --all --profile prof_dev

# Edit the CDK code with an editor of your choice (Visutal Studio Code is recommended)
#...

# linting (check the appearance)
npm run lint

# Orthopedic
npm run format

# Run snapshot test (see NOTE)
npm run test

# Deploy (to speed up the process, we have specified an option not to ask for approval and not perform a rollback)

npx aws-cdk deploy --all --profile prof_dev --require-approval never --no-rollback

# Again diff, modify, test, and deploy ...

NOTE:

If you change the CDK code, the snapshot test (npm run test) will fail because a different template is generated than before If the template has been generated correctly, the snapshot needs to be updated as follows:

# Update snapshot
npm run test -- -u

3. Manipulate all BLEA use cases together

To verify and test all use cases, use workspaces and run the following:

# Run in BLEA root directory
npm ci
npm run lint
npm run format
npm run clean --workspaces
npm run test --workspaces -- -u # updatesnaphosts
npm run test --workspaces

NOTE:

To test individual use cases using workspaces, run the following: Note the difference between workspaces and workspaces.

# Run in BLEA root directory
npm run test --workspace usecases/blea-gov-base-standalone

4. install additional packages

If the CDK code requires additional packages, install them as follows: Here we are installing @aws -cdk/aws-kms

# Run in BLEA root directory
npm i-P @aws -cdk/aws-kms --workspace usecases/guest-webapp-sample

Remediate Security Issues

Even after deploying a governance base, there are detections that are reported at a critical or high severity level in Security Hub benchmark reports . You will need to take action on these manually.

Optional: You can also disable Security Hub detections (not recommended. (If you want to disable it, please do so after fully evaluating the security risk.)

1. Enable MFA for the root user

You must manually configure MFA for the root user. A root user is a user who logs in with an email address when logging into the Management Console.

Security Hub controls related to MFA (CRITICAL level)

How to repair

1. Access the root user of an Organizations member account
2. Enable Hardware MFA for the Root User

2. Using IMDSv2 for EC2 metadata access

It is recommended that you use IDMSv2 only for metadata access on EC2 instances. Refer to the following documents for remediation:

3. Changing the status of notifications about CodeBuild's privileged mode

CodeBuild should only enable privileged mode when building Docker images. If the following controls are out of compliance, check to see if the CodeBuild project needs to enable privileged mode, and if so, change the status of the workflow to SUPPRESSED.

Refer to the following document how to change the status of a workflow.

ttps://docs.aws.amazon.com/securityhub/latest/userguide/finding-workflow-status.html