Merge pull request #23 from RyosukeDTomita/feature/markdownlint

Use markdownlinter to format markdown

README.md

@@ -21,9 +21,9 @@ Sample React application for Trying to Use DevSecOps tools.
 
 ## ENVIRONMENT
 
-- AWS: ECS on Fargate に Code Pipeline 経由でデプロイする。サンプルでは dev と prod 環境を用意し、dev 環境で動作確認後に承認ボタンを押すと prod 環境にもデプロイが進む形になっている。
-- Github Actions
-- application: create-react-app で作られるやつ
+- AWS: ECS on FargateにCode Pipeline経由でデプロイする。サンプルではdevとprod環境を用意し、dev環境で動作確認後に承認ボタンを押すとprod環境のデプロイが進む形になっている。
+- GitHub Actions
+- application: create-react-appで作られるデフォルトそのまま。
 
 ---
 
@@ -66,12 +66,12 @@ See [./doc/tools_doc](./doc/tools_doc)
 
 ### AWS Settings
 
-copilot cli を使って環境構築を行う。
+copilot cliを使って環境構築を行う。
 
 #### Create app
 
-- 名前は任意だが，自分は react-app とした
-- ここで必用な IAM ロールの一部や KMS のキーや CodePipeline に使う S3 やそのポリシーが作成されている。
+- 名前は任意だが，自分は`react-app`とした
+- ここで必用なIAMロールの一部やKMSのキーやCodePipelineに使うS3やそのポリシーが作成されている。
 
 ```shell
 copilot app init
@@ -81,10 +81,10 @@ application: react-app
 
 #### development 用のと production 用の 2 つの environment と service を作成する
 
-- amd64 を指定しないとビルドエラーになる。
-- 名前は任意だが，dev-env，dev-svc と prod-env，prod-svc とした。
-- Type は Load Balancer を選択した。
-- 新しい VPC や，ECS の Cluster，Load Balancer や権限周りが作成される。
+- amd64を指定しないとビルドエラーになった。TODO
+- 名前は任意だが，dev-env，dev-svcとprod-env，prod-svcとした。
+- TypeはLoad Balancerを選択した。
+- 新しいVPCや，ECSのCluster，Load Balancerや権限周りが作成される。
 
 ```shell
 DOCKER_DEFAULT_PLATFORM=linux/amd64 copilot init
@@ -131,13 +131,13 @@ Default environment configuration? No, I'd like to import existing resources
 
 </details>
 
-- environment をデプロイ
+- environmentをデプロイ
 
 ```shell
 copilot env deploy
 ```
 
-- service をデプロイする。
+- serviceをデプロイする。
   > [!WARNING]
   > この際に間違えて dev-svc や dev-env を選ばないように注意する。
 
@@ -154,13 +154,13 @@ copilot svc show # urlが出てくるのでそこにアクセスする
 
 ### CodePipeline の作成
 
-- 名前は任意だが，自分は react-app-pipeline とした。
+- 名前は任意だが，自分はreact-app-pipelineとした。
 
 ```shell
 copilot pipeline init
 ```
 
-- [manifest.yml](./copilot/pipelines/react-app-pipeline/manifest.yml)を編集して development でサービス開始後にユーザが承認した後に production にデプロイされるようにする。
+- [manifest.yml](./copilot/pipelines/react-app-pipeline/manifest.yml)を編集してdevelopmentでサービス開始後にユーザが承認した後にproductionにデプロイされるようにする。
 
 ```yaml
 requires_approval: true
@@ -233,43 +233,43 @@ git secrets --install
 git secrets --register-aws # awsのクレデンシャル検知ルールを登録
 ```
 
-- VSCode の Extensions もお好みで。Docker の hadolint はおすすめ。
+- VSCodeのExtensionsもお好みで。Dockerのhadolintはおすすめ。
 
-- GitHub Actions がスキャン結果のファイルをアップロードできるように権限をつける。詳細は[semgrep の yaml](./.github/workflows/react-semgrep.yaml)を参照。
+- GitHub Actionsがスキャン結果のファイルをアップロードできるように権限をつける。詳細は[semgrepのyaml](./.github/workflows/react-semgrep.yaml)を参照。
 
 ---
 
 ## HOW TO USE
 
 1. [PREPARING](#preparing)の設定を先にやる。
-2. commit 時には pre-commit と git-secret が作動
-3. push 時には GitHub Actions により SAST(semgrep)，UnitTest(jest)，Dependency Check(trivy)が実行される。
-4. master ブランチにマージしたり master に push した時に CodePipeline によって AWS へリポジトリがクローンされ，ビルド(image scan を含む)，development へのデプロイが始まる。
-5. development で問題がなければ CodePipeline 上で承認し，production へデプロイ
+2. commit時にはpre-commitとgit-secretが作動
+3. push時にはGitHub ActionsによりSAST(semgrep)，UnitTest(jest)，Dependency Check(trivy)が実行される。
+4. masterブランチにマージしたりmasterにpushした時にCodePipelineによってAWSへリポジトリがクローンされ，ビルド(image scanを含む)，developmentへのデプロイが始まる。
+5. developmentで問題がなければCodePipeline上で承認し，productionへデプロイ
 
 ---
 
 ## Error Log
 
 ### Code Build のエラー
 
-以下コマンドでログが見れる。もしくは Code Deploy で見ても良い。
+以下コマンドでログが見られる。ブラウザのAWS Code Deploy
 
 ```shell
 copilot svc logs --previous
 ```
 
 ### nginx: [emerg] bind() to 0.0.0.0:80 failed (13: Permission denied)
 
-- [ECS の仕様で非特権ユーザを使用したコンテナでは 80 番ポートが使えないっぽい](https://repost.aws/questions/QU1bCV9wT4T5iBrrP1c2ISfg/container-cannot-bind-to-port-80-running-as-non-root-user-on-ecs-fargate) --> つまり，local の docker で 80 でサービスが起動できても ECS だと権限エラーになる。このため，コンテナで開放する port は 8080 としている(ALB に対して 8080 がマッピングされているためブラウザからは 80 でアクセスできる)。
+- [ECS の仕様で非特権ユーザを使用したコンテナでは 80 番ポートが使えないっぽい](https://repost.aws/questions/QU1bCV9wT4T5iBrrP1c2ISfg/container-cannot-bind-to-port-80-running-as-non-root-user-on-ecs-fargate) --> つまり，localのdockerで80でサービスが起動できてもECSだと権限エラーになる。このため，コンテナで開放するportは8080としている(ALBに対して8080がマッピングされているためブラウザからは80でアクセスできる)。
 
-### toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit
+### toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: <https://www.docker.com/increase-rate-limit>
 
-- Docker Hub に短期間にアクセスしすぎているだけなので放置で OK
+- Docker Hubに短期間にアクセスしすぎているだけなので放置でOK
 
 ### Error response from daemon: dockerfile parse error
 
-- Dockerfile の RUN をヒアドキュメントで書いていたら怒られた(ローカルでは動いてたのに...)
+- DockerfileのRUNをヒアドキュメントで書いていたら怒られた(ローカルでは動いてたのに...)
 
 ```dockerfile
 # 修正前Dockerfile
@@ -289,12 +289,12 @@ RUN mkdir -p /var/log/nginx \
 
 ### Resource handler returned message: "Error occurred during operation 'ECS Deployment Circuit Breaker was triggered'
 
-コンテナが正常に起動していない。amd64 を指定したら動いた。
+コンテナが正常に起動していない。amd64を指定したら動いた。
 
 ```shell
 DOCKER_DEFAULT_PLATFORM=linux/amd64 copilot deploy
 ```
 
 ### copilot app show で CFn スタックを消したはずのアプリが表示されてしまう
 
-- copilot app show は Parameter Store を見ているのでそこを消す。
+- `copilot app show`はParameter Storeを見ているのでそこを消す。

doc/github-actions.md

@@ -7,7 +7,7 @@
 
 ### GitHub Actions の Workflow
 
-- リポジトリの Actions のページから**Create status badge**をクリックして README.md に貼り付ける。
+- リポジトリのActionsのページから**Create status badge**をクリックしてREADME.mdに貼り付ける。
 
 ![バッチのつけかた](./fig/badge.png)
 

doc/tools_doc/aqua.md

@@ -0,0 +1,4 @@
+# aqua
+
+## Reference
+- [github](https://github.com/aquaproj/aqua)

doc/tools_doc/git-secret.md

@@ -1,7 +1,7 @@
 # git secrets
 
 - パスワードのシークレットと思われる文字列を検知する。
-- pre-commit を使って実装されているらしい。
+- pre-commitを使って実装されているらしい。
 
 ## 環境構築
 
@@ -28,4 +28,4 @@ git secrets --list # 設定を確認
 git secrets --scan # スキャン
 ```
 
-- また，コミットしようとした際にも scan が実行されており，特定の文字列が検知されるとコミットできなくなる。
+- また，コミットしようとした際にもscanが実行されており，特定の文字列が検知されるとコミットできなくなる。

doc/tools_doc/hadolint.md

@@ -1,9 +1,9 @@
-# hadolint の使い方
+# hadolintの使い方
 
 ## 概要
 
 > [hadolint github](https://github.com/hadolint/hadolint)
-> Dockerfile を綺麗にするツール。
+> Dockerfileを綺麗にするツール。
 
 ---
 
@@ -30,4 +30,4 @@ hadolint --trusted-registry grc.io ./myapp/Dockerfile # --trusted-registryに登
 
 ## エラー例
 
-- /Dockerfile:7 DL3059 info: Multiple consecutive `RUN` instructions. Consider consolidation. --> RUN を一つにまとめたほうがイメージのレイヤーを最小化できる。
+- /Dockerfile:7 DL3059 info: Multiple consecutive `RUN` instructions. Consider consolidation. --> RUNを1つにまとめたほうがイメージのレイヤーを最小化できる。

doc/tools_doc/markdown_tools.md

@@ -1,45 +1,53 @@
-# Markdown用のツール(VSCodeの例)
+# Markdown用のツール(VSCode例)
 
-## README.md
+## README.mdをいい感じにする
+
+### linterの導入
 
-### linter
 - [markdown-lint](https://github.com/markdownlint/markdownlint)
 
 ```shell
 git clone https://github.com/markdownlint/markdownlint
 cd markdownlint
 rake install
 ```
-- VSCodeのExtensionsmarkdown-linterを追加
+
+- VSCodeのExtensionsmarkdown-linterを追加。settings.jsonは以下で設定。
 
 #### 警告の抑止
+
 - [設定項目の一覧](https://spure.dev/markdownlint_setting/)を見ながら対応する。
-- [settings.json](#settings\.json)での抑止
 - markdown内での抑止はコメントを使う。
 
 ```md
 <!-- markdownlint-disable MD033 -->
 ```
 
-### formatter
-- VSCodeのPrettierを使う
+- VSCodeで使うならsettings.jsonによく使う警告設定をまとめておく。
+
+```json
+  // 抑止設定
+  "markdownlint.config": {
+    "MD010": false, // タブ
+    "MD013": false // 長い行
+  }
+```
+
+### formatterの導入
 
-### settings\.json
+- ~~VSCodeのPrettierを使う~~
+Prettierを使うと日本語と英語の間に謎の空白がはいるのでmarkdownlintをformatterとして使う。
 
 ```json
   // markdown
   "[markdown]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint",
     "editor.formatOnSave": true,
   },
-  // 抑止設定
-  "markdownlint.config": {
-    "MD010": false, # タブ
-    "MD013": false # 長い行
-  }
 ```
 
-### snippetsについて
+### VSCodeにsnippetsを設定する
+
 - snippetは~/.config/Code/User/snippets/以下に格納する。
 - .vscode/以下に配置するとプロジェクトメンバーで共有できる。
 - command parreteで`snippets`を調べると言語ごとに登録可能。

doc/tools_doc/pre-commit.md

@@ -2,11 +2,11 @@
 
 ## 概要
 
-- git のコミット時に linter 等を実行させるのに使う。
+- gitのコミット時にlinter等を実行させるのに使う。
 
 ---
 
-## インストール
+## install
 
 ```shell
 pip install pre-commit
@@ -16,7 +16,7 @@ pre-commit install
 
 ### インストール時のエラー
 
-- `AttributeError: module 'virtualenv.create.via_global_ref.builtin.cpython.mac_os' has no attribute 'CPython2macOsFramework'`がでている。これは virtualenv に関連するエラーなので upgrade したりしてみる。
+- `AttributeError: module 'virtualenv.create.via_global_ref.builtin.cpython.mac_os' has no attribute 'CPython2macOsFramework'`がでている。これはvirtualenvに関連するエラーなのでupgradeしたりしてみる。
 - [pipenv の初期化時に発生するエラー](https://qiita.com/akis1215/items/11c9ca506cac8bcde5d9)を参考に入れ直したら直った。
 
 ```shell
@@ -29,15 +29,15 @@ sudo pip3 install virtualenv
 ## 使い方
 
 - [pre-commit を使うサンプル](https://zenn.dev/yiskw713/articles/3c3b4022f3e3f22d276d)を見ながら設定する。
-- **linter からエラーがでるとコミットできないので注意**
-- .pre-commit-config.yaml をいじって`pre-commit install`して git commit すると動作が確認できる。
+- **linterからエラーがでるとコミットできないので注意**
+- .pre-commit-config.yamlをいじって`pre-commit install`してgit commitすると動作が確認できる。
 - **デフォルトでは変更されたファイルに対してのみしか実行**されないので注意が必用。全体のチェックをしたいなら手動で行える。
 
 ```shell
 pre-commit run --all-files
 ```
 
-- 以下は hadolint(Dockerfile のスキャン)を実行する.pre-commit-config.yaml の例
+- 以下はhadolint(Dockerfileのリンター)を実行するための`.pre-commit-config.yaml`の例
 
 ```yaml
 default_stages: [commit]
@@ -60,9 +60,9 @@ repos:
 
 > 詳細は[pre-commit 公式ドキュメントを見る](https://pre-commit.com/)
 
-- id: [対応している hook 一覧](https://pre-commit.com/hooks.html)を見るとわかる?コマンド名をいれておけばよさそう?
-- rev: latest は指定できないのでメンテが必用そう
-- files: スキャン対象を正規表現で絞れる。**スキャン対象のファイルが見つからない時につけても意味ない。**パスは id の args とかで指定する。
+- id: [対応している hook 一覧](https://pre-commit.com/hooks.html)を見てコマンド名をいれておけばよさそう。
+- rev: latestは指定できないのでメンテが必用そう
+- files: スキャン対象を正規表現で絞れる。**スキャン対象のファイルが見つからない時につけても意味ない。**パスはidのargsで指定する。
 - exclude: スキャン対象から除外するものを指定できる。
 
 ### eslint を使う
@@ -106,7 +106,7 @@ pre-commit run -a
 
 ## エラー
 
-- md の最後が## test のような形で終わっており，内容がないとエラーになる
+- mdの最後が## testのような形で終わっており，タグに要素がないとエラーになる。
 
 ```shell
 Fix End of Files.........................................................Failed

doc/tools_doc/semgrep.md

@@ -13,12 +13,12 @@ semgrep ./frontend-app
 
 ### VSCode Extensions
 
-- 最初に Sign in する必用がある。
-- Ctrl shift p で実行する。
+- 最初にSign inする必用がある。
+- Ctrl shift pで実行する。
 
-### Github Actions で semgrep を使う
+### GitHub Actions で semgrep を使う
 
-- 事前にリポジトリの設定から --> Code and automation --> Actions --> General の Workflow permissions を Read and write permissions に変更しておく必用がある。
+- 事前にリポジトリの設定から --> Code and automation --> Actions --> GeneralのWorkflow permissionsをRead and write permissionsに変更しておく必用がある。
 
 ```json
 name: Semgrep Full Scan

doc/tools_doc/trivy.md

@@ -16,12 +16,12 @@ sudo apt-get install trivy
 
 ## オプション
 
-- --vuln-type は os と library が選べる。指定しないと両方になる。これは絞らなくても良さそう。
-- --no-progress: 進捗バーを表示しない。CI/CD で出力をシンプルにする。
-- --exit-code 1: スキャンで脆弱性が出た時にステータスコード 1 を返すため CI/CD ツールなどで結果を評価しやすくなる。
+- --vuln-typeは`os`と`library`が選べる。指定しないと両方になる。これは絞らなくても良さそう。
+- --no-progress: 進捗バーを表示しない。CI/CDで出力をシンプルにする。
+- --exit-code 1: スキャンで脆弱性が出た時にステータスコード1を返すため，CI/CDツールなどで結果を評価しやすくなる。
 - --format table: 結果をテーブル形式で表示
 - fs: ファイルスキャンモード
-- --scanners vuln: 脆弱性スキャンモードを指定。Secrets(デフォルト on)や misconfig(デフォルト off)，license(デフォルト off)なども指定できる
+- --scanners vuln: 脆弱性スキャンモードを指定。Secrets(デフォルトon)やmisconfig(デフォルトではoff)，license(デフォルトではoff)なども指定できる
 - --vuln-type library: スキャン対象をライブラリに限定する。
 
 ---
@@ -59,8 +59,8 @@ trivy sbom test.json # sbomを解釈
 
 #### docker image のスキャン
 
-- Docker image で使っているライブラリの脆弱性を探す。
-- Dockerfile を用意する
+- Docker imageで使っているライブラリの脆弱性を探す。
+- Dockerfileを用意する
 
 ```shell
 FROM registry.access.redhad.com/ubi8/ubi:8.2
@@ -85,7 +85,7 @@ trivy sbom test.json
 
 ## エラー
 
-- image スキャンでコンテナを実行していない(docker container ps がない)
+- imageスキャンでコンテナを実行していない(`docker container ps`がない)時のエラー
 
 ```shell
 2023-12-05T22:31:00.272+0900	FATAL	image scan error: scan error: unable to initialize a scanner: unable to initialize a docker scanner: 4 errors occurred: