Skip to content

Latest commit

 

History

History
443 lines (303 loc) · 17.1 KB

HowTo.md

File metadata and controls

443 lines (303 loc) · 17.1 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-ecsapp-sample.ts",
  "requireApproval": "never",
  "rollback": false,
  "context": {
    "dev": {

Manage personal environment by cdk.context.json

You can specify parameters for your development environment by placing cdk.context.json in the same directory as cdk.json. This file will not be committed to the repository. This file may have been created automatically by the CDK. In this case, keep the existing configuration and add your own Context definition.

cdk.context.json example

{
  "@aws-cdk/core:enableStackNameDuplicates": "true",
  "aws-cdk:enableDiffNoFail": "true",
  "@aws-cdk/core:stackRelativeExports": "true",
  "my": {
    "description": "Personal Environment variables for blea-guest-*-samples.ts",
    "envName": "Personal",
    "vpcCidr": "10.100.0.0/16",
    "monitoringNotifyEmail": "[email protected]",
    "dbUser": "personaluser",
    "slackNotifier": {
      "workspaceId": "T8XXXXXXXXX",
      "channelIdMon": "C02YYYYYYYY"
    }
  }
}

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 Context file

Set the Slack workspace ID and Channel ID for cdk.json or cdk.context.json as follows: Specify a different channel for security and monitoring:

For security (governance baseline):

      "slackNotifier": {
        "workspaceId": "T8XXXXXXX",
        "channelIdSec": "C01XXXXXXXX",
      }

For monitoring (sample application):

      "slackNotifier": {
        "workspaceId": "T8XXXXXXX",
        "channelIdMon": "C01YYYYYYYY"
      }
key value
WorkspaceID Copy from Workspace details in AWS Chatbot
ChannelIDSec Copy from Slack App - For Security Alarms
ChannelIdMon Copy from Slack App - For Monitoring Alarms
ChannelidaGG Copy from Slack App - For alarms for aggregated information in your Audit account

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/guest-webapp-sample
npx cdk deploy --all -c environment=dev --profile prof_dev

NOTE

ts files will be built by npx cdk deploy command. Because its command will call npx ts-node --prefer-ts-exts internally.

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.

Accessing context in application

Context specified in cdk.json or cdk.context.json is accessed as follows in CDK code (bin/*.ts).

const envKey = app.node.tryGetContext('environment');
const valArray = app.node.tryGetContext(envKey);
const environment_name = valArray['envName'];

An example of how to deploy using the Context parameter.

cdk deploy --all --profile prof_dev  -c environment=dev
cdk deploy --all --profile prof_prod -c environment=prod

  • If —-app is not specified, the Application specified in app of cdk.json will be deployed.

  • Specify —-profile xxxxx to specify a profile (credentials) for deployment

  • Specify -c envrionment=xxxx to specify the Context parameter defined in cdk.json.

  • The account and region for the credentials specified in profile must match the account and region specified in env in the Context. This prevents you from deploying to the wrong account, and also keeps a record of which account you deployed with which context. It is recommended to specify env as much as possible in context.

  • If the account used by each developer is different, such as in the development environment, there is a way to not specify env in context. If env is not set, it will be deployed to the account and region of the credentials specified in profile.

  • See: [https://docs.aws.amazon.com/ja_jp/cdk/latest/guide/context.html]

  • See: [https://docs.aws.amazon.com/ja_jp/cdk/latest/guide/get_context_var.html]

Development process

Once deployed, the flow of editing, building, and deploying the CDK code looks like this:

1. Go to the use case directory

cd usecases/guest-webapp-sample

2. Clean up your environment

npm run clean

3. Edit CDK code

Edit the CDK code in any editor. (Visutal Studio Code is recommended)

4. Install additional packages if needed

If your CDK code requires additional packages, install them as follows: Here we have @aws -cdk/aws-kms installed.

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

5. Test

# linting
npm run lint
# formatting
npm run format
# snapshot test
npm run test

NOTE: When you update a CDK source code, your snap shot test (npm run test) will be failed because a generated template is differ from previous one. If your CDK code is correct, you need to update a snapshot using command below.

# Update snapshot
npm run test -- -u

To test all use cases, run the following using workspaces:

# Run in the root directory of BLEA
npm ci
npm run lint
npm run format
npm run clean --workspaces
npm run test --workspaces -- -u      # update snaphosts
npm run test --workspaces

To test an individual use case using workspaces: Note the difference between workspaces and workspaces.

# Run in the root directory of BLEA
npm run test --workspace usecases/guest-webapp-sample

6. Synth/Diff

Create a CDK Asset and see the differences from the current environment.

npx cdk synth --all --app "npx ts-node --prefer-ts-exts bin/blea-guest-ecsapp-sample.ts" -c environment=dev --profile prof_dev --require-approval never --no-rollback
npx cdk diff --all --app "npx ts-node --prefer-ts-exts bin/blea-guest-ecsapp-sample.ts" -c environment=dev --profile prof_dev --require-approval never --no-rollback

7. Deploy

Deploy it. Here we have added an option to skip authorization and not roll back.

npx cdk deploy --all --app "npx ts-node --prefer-ts-exts bin/blea-guest-ecsapp-sample.ts" -c environment=dev --profile prof_dev --require-approval never --no-rollback

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.

[https://docs.aws.amazon.com/securityhub/latest/userguide/finding-workflow-status.html]