自己流の手順書フォーマットを公開してみた

のんピの手順書の極意が見れるってよ。

#オペレーション

#Markdown

#VSCode（Visual Studio Code）

のんピ

2021.07.15

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

手順書フォーマットは千差万別

みなさんは自己流または、組織やプロジェクトで定められた手順書のフォーマットはありますか? 私は自己流の手順書フォーマットがあります。

自己流の手順書フォーマットがあるといっても、かなり扱いがふわふわしているので、備忘やメモの意味合い強めでまとめていきます。

「もっとこうした方がいいよ!!」などフィードバックがあれば、ぜひお願いします!

いきなりまとめ

手順書はExcelやスプレッドシートではなく、Markdownで書く
- 手順書はgitで管理する
5W1Hを意識して手順書を書く
基本的にはCLIを使った手順書にする

手順書はExcelやスプレッドシートではなく、Markdownで書く

手順書をExcelやスプレッドシートで書くメリット・デメリット

手順書をExcelやスプレッドシートで書いている方も多いと思いますが、私はMarkdownで書いています。

Excelやスプレッドシートを使って手順書を書くメリットは以下だと考えます。

使っている人が多く、学習コストが低い
手順を項目毎にまとめやすい
横並びに情報を記載することができる
関数やVBAを使うことで手順書内で処理を行うことができる

この様な「昔から慣れ親しんでいて直感的に書けるし、ちょっと工夫すれば楽もしやすい」というのが、よく使われる理由と考えました。

一方で、Excelやスプレッドシートを使って手順書を書くデメリットは以下だと考えます。

謎のセル結合や、細かいプロパティが裏で設定されている場合に再利用がしづらい
レイアウトを変更する際に重労働になりがち
手順の更新前後で比較がしづらい
- WinMergeなどを使えば、見づらいですが差分を確認することはできます
Excelやスプレッドシートがバイナリファイルであるため、gitを使った変更管理、変更経緯の把握がしづらい
【お客様提出版】【令和最新版】20210504_xxxx様_操作手順書_20200714_03_のんピ確認済み（2）_部長レビュー待ち.xlsxのような謎ファイル名が気づいたら大量生成されがち

このようなデメリットに私は疲弊してしまったので、Excelからの乗り換えを検討しました。

手順書をMarkdownで書くメリット

上述した理由でExcelで手順書を書くことに嫌気が差した私はMarkdownで書いています。Markdownを選択した理由は以下の通りです。

プレーンテキストと比較して、リッチな見た目で目に優しい
Excelやスプレッドシートがインストールされていない環境でも使える
テキストファイルなので、diffなどで手順書の間の比較がしやすい
gitで管理がしやすくなり、レビュアーにも優しい
grepを使って複数のファイルを横断して該当文字列を検索することができる

大体は見たまんまの内容ですが、プレーンテキストと比較して、リッチな見た目で目に優しい について補足します。

「Markdown書きづらくね??」という声が聞こえてくる気がしますが、こちらはエディターの機能に助けられながら書いています。

私はVS CodeでMarkdownを書いており、主に以下の拡張機能に助けられています。

Markdown All in One: 目次(TOC)の作成と章番号の追加・更新
Markdown Preview Enhanced: Markdownのプレビュー及び、HTMLへのエクスポート
markdownlint: Markdownのlint

Markdown All in One及び、Markdown Preview Enhancedの具体的な使い方は後述します。(markdownlintはデフォルトの設定で使っています。)

5W1Hを意識して手順書を書く

手順書の中で書くこと

良い手順書、悪い手順書の定義は人によると思いますが、私が考える良い手順書の定義は以下の通りです。

何をするための手順書なのか腹落ちしてから作業できる
読み手の理解や操作手順を統一できる
後で手順書を見返したときに、どの様な作業結果になったのかが分かる

その様な良い手順書になるように、私は5W1Hを意識して、操作手順だけではなく以下のような内容も記載しています。

ドキュメント作成者
改訂履歴
このドキュメントの目次
このドキュメントの目的・概要
前提条件
作業完了条件
作業者
副作業者 (チェッカー)
作業場所
作業端末
予定作業時間
その他制約事項・備考
参考情報
作業実績
- 作業結果
- OK or NG
- NGと判断した理由
- NGとなった原因
- 次回アクション
- 作業開始・終了時間

手順書の例

手順書の書き方

実際に私がVS CodeでMarkdownを書くときは、以下の様にアウトラインとプレビューを表示させながら書いています。

Markdownで黙々と書いていても、正しく書けているのか不安になったりするので、アウトラインとプレビューがあるだけでかなり書きやすさが変わります。

プレビューはリアルタイムで更新されるので、文字を入力した時や、画像を指定した瞬間に反映されます。

太字やコードブロックなどでテキストを修飾することもできます。

使用しているVS Codeの拡張機能の使い方

ここで、私が使用しているVS Codeの拡張機能である Markdown All in One と、Markdown Preview Enhanced の使い方について補足します。

Markdown All in One

Markdown All in Oneは目次(TOC)の作成と章番号の追加・更新を行うために使用しています。

まず、目次(TOC)の作成についてです。

HTMLへのエクスポートしてしまうと、VS Codeのアウトラインは確認できません。そのため、目次を追加してVS Code以外で手順書を開く場合にも全体概要を把握しやすくしてあげます。

目次を追加する際は、目次を追加したい箇所にカーソルを合わせた状態で、VS Codeのコマンドパレットを開きます。
そして、コマンドパレットで>TOCなどと入力すると、以下の様に Markdown All in One: Create Table of Contentsが表示されるので、こちらをクリックします。

すると、以下の様に目次が作成されます。

作成された目次は単なるプレーンテキストではなく、目次をクリックすると該当の章にジャンプします。

また、手順書のタイトルである#から始まる見出しは目次に含めて欲しくないため、以下の様に見出しの前の行にを追加しています。

<!-- omit in toc -->
# 2021-07-14 株式会社XXXXX様 SIEM on Amazon ES環境設定手順

続いて、章番号の追加・更新です。

章番号を追加することによって、具体的にどこの手順で詰まったのかの共有や、手順書修正をメンバーに依頼する際に便利です。

章番号の追加・更新をする際も、まずVS Codeのコマンドパレットを開きます。
そして、コマンドパレットで>sectionなどと入力すると、以下の様に Markdown All in One: Add/Update section numbersが表示されるので、こちらをクリックします。

すると、以下の様に章の先頭に章番号が自動で追加されます。

章の階層の変更や、章が追加された場合も同様の手順で、章番号の更新ができます。

Markdown Preview Enhanced

Markdown Preview Enhancedは、Markdownのプレビュー及び、HTMLへのエクスポートのために使用しています。

まず、Markdownのプレビューについてです。

VS Codeの標準機能にもMarkdownのプレビュー機能がありますが、プレビューのスタイルを変更するにはCSSを自分で編集する必要があったり、プレビューのチェックボックスにチェックを入れることができなかったりと、微妙に使いづらいです。

Markdown Preview Enhancedでプレビューを表示すると、そんな悩みが解決できます。

Markdown Preview Enhancedでプレビューを表示する際は、プレビューを表示したいMarkdown上で右クリックして、Markdown Preview Enhanced: Open Preview to the Sideをクリックします。

すると、以下の様にプレビューが表示されます。

プレビュー上で右クリックをすると、各種メニューが表示され、Preview Themaから任意のテーマを選択することができます。

また、プレビューのチェックボックスにチェックを入れることもでき、プレビューで入れたチェックはMarkdownファイルにも反映されます。

続いて、HTMLへのエクスポートです。

実際の作業環境では、VS CodeなどMarkdownが扱えるエディターが使えない場面もあります。

そのようなときはMarkdownをHTMLにエクスポートします。(ポータブルモードのVS Codeを作業環境に持ち込んで対応しても良いと思います)

HTMLへのエクスポートはプレビュー上で右クリックをして、HTML -> HTML(offline)を選択することで行えます。

すると、Markdownファイルが保存されている同じディレクトリにHTMLファイルがエクスポートされます。

HTMLファイルをブラウザで開くと、以下の様にプレビューと同じスタイルの手順書を確認できます。

手順書の例

ご参考までに上述の手順書のMarkdownを以下に記載します。

<!-- omit in toc -->
# 2021-07-14 株式会社XXXXX様 SIEM on Amazon ES環境設定手順

## 1. ドキュメント作成者

CM) のんピ(のんピのメールアドレス)

## 2. 改訂履歴

- 1.0:
  - 作成日時: 2021-07-12 13:48:45
  - 更新内容: 初版作成

## 3. このドキュメントの目次

- [1. ドキュメント作成者](#1-ドキュメント作成者)
- [2. 改訂履歴](#2-改訂履歴)
- [3. このドキュメントの目次](#3-このドキュメントの目次)
- [4. このドキュメントの目的・概要](#4-このドキュメントの目的概要)
- [5. 前提条件](#5-前提条件)
- [6. 作業完了条件](#6-作業完了条件)
- [7. 作業者](#7-作業者)
- [8. 副作業者 (チェッカー)](#8-副作業者-チェッカー)
- [9. 作業場所](#9-作業場所)
- [10. 作業端末](#10-作業端末)
- [11. 予定作業時間](#11-予定作業時間)
- [12. その他制約事項・備考](#12-その他制約事項備考)
- [13. 参考情報](#13-参考情報)
- [14. 作業実績](#14-作業実績)
  - [14.1. 作業結果](#141-作業結果)
    - [14.1.1. OK or NG](#1411-ok-or-ng)
    - [14.1.2. NGと判断した理由](#1412-ngと判断した理由)
    - [14.1.3. NGとなった原因](#1413-ngとなった原因)
    - [14.1.4. 次回アクション](#1414-次回アクション)
  - [14.2. 作業開始・終了時間](#142-作業開始終了時間)
- [15. 手順書](#15-手順書)
  - [15.1. ログイン [想定作業時間: 3分]](#151-ログイン-想定作業時間-3分)
  - [15.2. スイッチロール [想定作業時間: 3分]](#152-スイッチロール-想定作業時間-3分)

## 4. このドキュメントの目的・概要

株式会社XXXXX様(以下XXX)のSIEM on Amazon ESの環境設定を行うための手順書。  
既存お客様環境にはログ集約の仕組みはないため、新規にSIEM on Amazon ESをVPC上にデプロイし、SIEM on Amazon ESにログを集約し、分析する。

なお、本作業ではSIEM on Amazon ES用AWSアカウント(`123456789012`)以外のAWSアカウント上のリソースからのログ集約は行わない。

設定範囲は以下の通り。  

![全体構成図](./images/全体構成図.png)

設定するリソースは以下の通り。

- VPC: 1
- VPC Flow Logs: 1
- DHCP Options Sets: 1
- Subnet: 6
- Route Table: 6
- Internet Gateway: 1
- NAT Gateway: 1
- Elastic IP IP: 2
- Security Group: 2
- Network ACL: 1
- EC2 Instance: 1
- EBS Volume: 1
- CloudTrail: 1
- Secrutiy Hub: 1
- GuardDuty: 1
- IAM Access Analyzer: 1
- CloudWatch Logs
- Kinesis Data Firehose: 2
- SIEM on Amazon ES: 1
  - SIEM on Amazon ESをデプロイ時に作成されるリソースは、[SIEM on Amazon ESの公式ドキュメント](https://github.com/aws-samples/siem-on-amazon-elasticsearch-service/blob/main/README_ja.md#%E4%BD%9C%E6%88%90%E3%81%95%E3%82%8C%E3%82%8B-aws-%E3%83%AA%E3%82%BD%E3%83%BC%E3%82%B9)を参照

## 5. 前提条件

- [BacklogのWikiに記載したパラメーターシート](URL)をXXX様にレビューしていただいていること。
- XXX様のSIEM on Amazon ES用のAWSアカウント(`123456789012`)で、作業者の作業用のIAM Roleの作成が完了していること。
- 作業用端末に、[AWS Extend Switch Roles](URL)がインストール済みであり、`cm-XXX-Read`と、`cm-XXX-Admin`にスイッチロールする設定がされていること。

## 6. 作業完了条件

- 全てのリソースの作成が完了する。
- 作業者及び、副作業者が[BacklogのWikiに記載したパラメーターシート](URL)と実機とを見比べて、誤った設定がされていないと確認できる。

## 7. 作業者

CM) のんピ(のんピのメールアドレス)

## 8. 副作業者 (チェッカー)

CM) チバユキ(チバユキさんのメールアドレス)

## 9. 作業場所

岩本町ツインビル 7階

## 10. 作業端末

自端末(MacBook Pro 13-inch, 2020)

## 11. 予定作業時間

2021-07-14 09:00 〜 2021-07-14 16:00

## 12. その他制約事項・備考

- [お客様のBacklog](URL)は、IPアドレス制限をしているため、アクセスする際は、[こちらの手順](URL) を参考にVPN接続をすること。
- リソースの設定が出来次第、対応するBacklogの課題のステータスを`処理済み`に変更すること。
- 全ての作業が完了したら、XXX)xx様、XXX)yy様に連絡すること。
- **意図しない事象に遭遇した場合は、CM)チバユキさんに連絡すること。**

## 13. 参考情報

- [XXX他プロジェクト(XXXX)のBacklog](URL)
- [パラメーターシート](URL)
- [SIEM on Amazon ES公式ドキュメント](https://github.com/aws-samples/siem-on-amazon-elasticsearch-service/blob/main/README_ja.md)

## 14. 作業実績

以下項目は、作業終了後に入力すること

### 14.1. 作業結果

#### 14.1.1. OK or NG

以下に OK or NG を記入

```text

```

#### 14.1.2. NGと判断した理由

NGだった場合、以下に NGと判断した理由 を記入

```text

```

例)

```text
手順15.5.2. で意図しないエラーが発生したため。
エラー文は以下の通り。

error error error error error error
```

#### 14.1.3. NGとなった原因

NGだった場合、以下に NGとなった原因 を記入

```text

```

例)

```text
エラー文の`error`という文言と、リソースがxxな状態であることからIAMロールの権限不足だと考える
```

#### 14.1.4. 次回アクション

NGだった場合、以下に 原因解消のために次に行うべきアクション を記入

```text

```

例)

```text
以下の流れでアクションする
1. 検証環境にて、IAMロール 'test-role' にアタッチしているIAMポリシー `test-policy` で 'xxxx'を許可するように変更する
2. NGとなった15.5.2と同様の手順を実施し、エラーが解消されていることを確認する
3. エラーが解消されたことを確認して、お客様と次回作業日時をすり合わせる
```

### 14.2. 作業開始・終了時間

以下に 作業開始・終了時間(YYYY-MM-DD HH:MM 〜 YYYY-MM-DD HH:MM) を記入

```text

```

例)

```text
2021-07-14 10:10 〜 2021-07-14 12:25
2021-07-14 14:23 〜 2021-07-14 17:30
```

## 15. 手順書

### 15.1. ログイン [想定作業時間: 3分]

- [ ] [AWSマネージメントコンソールのURL](https://console.aws.amazon.com/console/home)をクリックする。
- [ ] 以下の必要な情報を入力して`サインイン`をクリックする。
  - [ ] アカウントID: `123456789012`
  - [ ] ユーザー名: `xxxxxxxx`
  - [ ] パスワード: `自分のIAMユーザーのパスワード`
- [ ] MFAコードを入力し、`送信`をクリックする。
- [ ] マネジメントコンソール上部に、**AWS マネジメントコンソール**を大きく表示されることを確認する。

### 15.2. スイッチロール [想定作業時間: 3分]

- [ ] ブラウザの拡張機能のAWS Extend Switch Rolesから、`cm-XXX-Read`をクリックする。
- [ ] マネジメントコンソール上部のメニューの`cm-XXX-Read`をクリックし、アカウントが、XXX様SIEM on Amazon ES用のAWSアカウントIDの`123456789012`であることを確認する。
- [ ] マネジメントコンソール上部の検索バーで`Lambda`と入力し、`Lambda`をクリックする。
- [ ] `cm-yamamoto-ryota-iamRole-LU-Level-upper`をクリックする。
- [ ] `テスト`タブをクリックする。
- [ ] 以下情報を入力し、`テスト`をクリックする。
  - [ ] 名前: `LevelUpFor3Hours`
  - [ ] テキストエリア:

```json
{
  "limit": "3:00"
}
```

- **実行結果: 成功**と表示され、`詳細`をクリックすると、**YYYY-MM-DD HH:MM:SSまで権限が与えられます**といった文章が表示されることを確認する。
- [ ] ブラウザの拡張機能のAWS Extend Switch Rolesから、`cm-XXX-Read`をクリックする。
- [ ] マネジメントコンソール上部のメニューの`cm-XXX-Admin`をクリックし、アカウントが、XXX様のSIEM on Amazon ES用のAWSアカウントIDの`123456789012`であることを確認する。

基本的にはCLIを使った手順書にする

GUIで操作すると作業証跡としてスクリーンショットを大量に撮らなければならない場面があると思います。

私はそんなスクリーンショット地獄を散々体験してしまったので、基本的にはCLIでの作業及び、何かあったときにログで作業内容を振り返れるようにしています。

CLIで作業をする際は、以下の様に実行結果の照らし合わせ及び、実行後のログを貼り付けるように記載しています。
お使いのTerratermやiTerm2などのターミナルのログを手順書と同じディレクトリに出力するようにしても良いかと思いますが、後で見返したときにこのログはどこの手順のログなのかというのが分かるようにすると、より良いと思います。

上述の手順書のMarkdownは以下の通りです。

#### 5.3. VPC Flow Logsの設定

- [ ] マネージメントコンソール上部のリージョン名を確認し、`東京`となっていることを確認する。
  - [ ] 東京でなかった場合は、リージョン名をクリックし、`アジアパシフィック(東京) ap-northeast-1`をクリックして、東京リージョンに移動する。
- [ ] マネージメントコンソール上部のCloudShellのアイコンをクリックし、CloudShellを起動する。
- [ ] CloudShellが入力可能状態になったら、以下コマンドでVPC Flow Logsを設定する。

```bash
$ aws ec2 create-flow-logs \
    --resource-type VPC \
    --resource-ids <作成したVPC ID> \
    --traffic-type ALL \
    --log-destination-type s3 \
    --log-destination arn:aws:s3:::prd-vpc-logs-123456789012 \
    --log-format '${version} ${account-id} ${interface-id} ${srcaddr} ${dstaddr} ${srcport} ${dstport} ${protocol} ${packets} ${bytes} ${start} ${end} ${action} ${log-status} ${vpc-id} ${subnet-id} ${instance-id} ${tcp-flags} ${type} ${pkt-srcaddr} ${pkt-dstaddr} ${region} ${az-id} ${sublocation-type} ${sublocation-id} ${pkt-src-aws-service} ${pkt-dst-aws-service} ${flow-direction} ${traffic-path}'
```

- [ ] コマンド実行後、以下のようなJSONが出力されることを確認する。

```json
{
    "ClientToken": "lZDlQQZaq1wIL18zmqYG4LU92ecwyK4idmSUkHSiRdI=",
    "FlowLogIds": [
        "fl-xxxxxxxxxxxxxxxxx"
    ],
    "Unsuccessful": []
}
```

- [ ] 以下コマンドでVPC Flow Logsが設定されているか確認する。

```bash
$ aws ec2 describe-flow-logs \
    --filter "Name=resource-id,Values=<作成したVPC ID>"
```

- [ ] コマンド実行後、以下のようなJSONが出力され、JSONの内容がパラメーターシートに記載した内容と一致していることを確認する。

```json
{
    "FlowLogs": [
        {
            "CreationTime": "2021-07-14T07:08:19.551000+00:00",
            "DeliverLogsStatus": "SUCCESS",
            "FlowLogId": "fl-xxxxxxxxxxxxxxxxx",
            "FlowLogStatus": "ACTIVE",
            "ResourceId": "<作成したVPC ID>",
            "TrafficType": "ALL",
            "LogDestinationType": "s3",
            "LogDestination": "arn:aws:s3:::prd-vpc-logs-123456789012",
            "LogFormat": "${version} ${account-id} ${interface-id} ${srcaddr} ${dstaddr} ${srcport} ${dstport} ${protocol} ${packets} ${bytes} ${start} ${end} ${action} ${log-status} ${vpc-id} ${subnet-id} ${instance-id} ${tcp-flags} ${type} ${pkt-srcaddr} ${pkt-dstaddr} ${region} ${az-id} ${sublocation-type} ${sublocation-id} ${pkt-src-aws-service} ${pkt-dst-aws-service} ${flow-direction} ${traffic-path}",
            "Tags": [],
            "MaxAggregationInterval": 600
        }
    ]
}
```

- [ ] コマンドの出力結果を以下に貼り付ける。

```json

```