# HowTo

[View this page in Japanese (日本語)](HowTo_ja.md)| [Back to Repository README](../README.md)

Here we will describe howTo for various settings.

- [VisualStudioCode Setup Instructions](#VisualStudioCode-Setup-Instructions)
- [Git pre-commit hook setup](#Git-pre-commit-hook-setup)
- [Skip Deployment Approvals and Don't Roll Back](#skip-deployment-approvals-and-dont-roll-back)
- [Set up Slack for AWS ChatBot](#set-up-slack-for-aws-chatbot)
- [Deployment with CloudShell](#deployment-with-cloudshell)
- [Update package dependencies](#update-package-dependencies)
- [Development process](#development-process)
- [Remediate Security Issues](#remediate-security-issues)

---

## 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:

- [EditorConfig](https://editorconfig.org/)
- [Prettier](https://prettier.io/)
- [ESLint](https://eslint.org/)

> NOTE:
>
> Code completion, jumping to definitions, and so on are implemented by [VSCode's built-in features](https://code.visualstudio.com/docs/languages/typescript). 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)](https://microsoft.github.io/language-server-protocol/).

### Installing and Initializing VSCode

Please install from [Visual Studio Code](https://code.visualstudio.com/)

For macOS, select [Running Visual Studio Code on macOS](https://code.visualstudio.com/docs/setup/mac) 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](../doc/images/VSCode-Recommended-Extensions.jpg)

This recommended extension is defined in `.vscode/extensions.json`. For more information about this feature, see [Managing Extensions in Visual Studio Code](https://code.visualstudio.com/docs/editor/extension-marketplace#_workspace-recommended-extensions).

### 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.

```json
    "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:

```sh
# 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](https://github.com/awslabs/git-secrets) according to the README Please Then run the following command to work with the git command:

```sh
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.

```text
    # 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.

- See: https://docs.aws.amazon.com/cdk/latest/guide/cli.html#cli-deploy

### 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.

```json
{
  "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

- See: https://docs.aws.amazon.com/chatbot/latest/adminguide/slack-setup.html

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):

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

For monitoring (sample application):

```typescript
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](../doc/images/CloudShell-OpenConsole.png)

### 2. Set up the CDK execution environment

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

- Update npm

```sh
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](../doc/images/CloudShell-UploadFiles.png)

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

```sh
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.

```sh
# 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

```sh
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

```sh
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:
>
> ```sh
> # 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:

```sh
# 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.
>
> ```sh
> # 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`

```sh
# 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.)

- https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-standards-enable-disable-controls.html

### 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)

- [CIS.1.13] Ensure MFA is enabled for the “root” account
  - https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-cis-controls.html#securityhub-cis-controls-1.13
- [CIS.1.14] Ensure hardware MFA is enabled for the “root” account
  - https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-cis-controls.html#securityhub-cis-controls-1.14
- [IAM.6] Hardware MFA should be enabled for the root user
  - https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-standards-fsbp-controls.html#fsbp-iam-6

#### How to repair

##### 1. Access the root user of an Organizations member account

- https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_access.html#orgs_manage_accounts_access-as-root

##### 2. Enable Hardware MFA for the Root User

- https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_enable_physical.html#enable-hw-mfa-for-root

### 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:

- [EC2.8] EC2 instances should use IMDSv2
  - https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-standards-fsbp-controls.html#fsbp-ec2-8

### 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.

- [CodeBuild.5] CodeBuild project environments should not have privileged mode enabled
  - https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-standards-fsbp-controls.html#fsbp-codebuild-5

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