AsciiDoc で「イイ感じ」な文書を作る - ラック・セキュリティごった煮ブログ

こんにちは、デジタルペンテスト部のねいちゃーどです。普段はチート対策ペネトレーションテストサービスの診断員として、主にゲームに関わるサービスの脆弱性診断を担当しています。

私たちのチームでは、お引き受けさせていただいた案件に対する成果物として「報告書」を作成・提出しています。報告書には「発見した脆弱性についての詳細なレポート」などが記載されています。端的に還元すれば「報告書を作成するのが本業」と言っても過言ではありません。

その報告書の作成には以前まで Microsoft Word (以下、Word) を用いていました。しかし Word を用いた報告書作成には、以下の問題がありました。

共同編集機能を用いた際に、編集内容が競合することがある
- その結果、同ファイルをリネームして上げ直さないといけなくなったり、代表者がローカルに落として編集した事例が過去にあった
- 「【最新版】打ち合わせ用の添付資料(7)(6)_yyyymmdd(4)_未記入項目アリ_絶対変えるな！_(現在田中さん編集中につき変更禁止)_B案バージョン.xls」(ゴミファイル名メーカーより)
Word 内の文章をコピー&ペーストした際に、意図せず書式までコピーされてしまう
- フォント・文字サイズ・装飾など
- これらは気をつけて (Ctrl + Shift + V による書式なしの) ペーストすれば問題ありませんが、全員が全てのペーストで気を使えるわけではない
誤ってデザインを変更し、報告書全体の装飾がぶっ壊れた

「報告書を作成するのが本業」ではありますが、報告書の内容ではなくその周辺の事柄で消耗するのは本意ではありません。なので、私たちのチームでは、記載する内容に注力するために、報告書の作成に使うツールを Word から AsciiDoc に乗り換えることにしました。

以下に AsciiDoc - Wikipedia から概要について引用しますが、つまるところ「Markdown 以上 HTML 以下の表現力があるマークアップ言語」です。

AsciiDocは軽量マークアップ言語のひとつである。 (中略) 対人可読な文書記述形式であり、文書の（論理）構造を意味付ける規則が平文形式である。ゆえに構文解析器を介することなく、テキストエディタなどを用いてAsciiDocで記述された文書を作成・閲読できる。HTMLを始めPDF、manページ、電子書籍、スライドといった種々の形式にDocBookツールチェーンを介して変換することが可能である。 AsciiDoc - Wikipedia

AsciiDoc は Markdown のようにテキストベースであることから、以下の恩恵を受けることができます。

普段使用しているテキストエディタで編集することができる
- 報告書を作成するためだけに Word を開かなくてよい
- VS Code, Vim, Emacs など、お好きなテキストエディタで報告書を作成できます
Git などのバージョン管理ツールで差分を管理することが容易である
- 編集内容が競合しても merge 等で解決することができるし、他所に上げ直す必要がなくなる
- 完成版しか出さない報告書であればほぼ無意味ですが、内々で使う「規約書」「運用手順書」を作成する際に、差分管理は役に立つ場面がある
テキストしか書かなくて良いので、文字に付随している装飾を気にする必要がない
- デザインは別ファイルで管理するので ~~使いまわし~~ 過去に作成した資産の再利用が容易である

AsciiDoc は、あくまでマークアップ言語の名前なので、使用しているツールではありません。実際に報告書を作成する際には Mogztter/asciidoctor-web-pdf を用いることにしました。以下、Windows 上の WSL2 上で anyenv 上の nodenv 内の npm でインストールするものとします (それぞれのインストール方法については割愛します) 。

asciidoctor-web-pdf をインストールする際に (2022/06/21 時点で最新の) v1.0.0-alpha.14 では「日本語のキャプションをつける際に表示されない」バグがあるようなので、現時点できちんと日本語が表示されることを確認されている v1.0.0-alpha.12 をインストールすることを推奨します。また asciidoctor-web-pdf で使っている @asciidoctor/core についても asciidoctor-web-pdf で当該バージョンが出たときのバージョンに合わせてインストールします。 (本来であればきちんと検証して本家に報告すべきことなのですが、業務の片手間でやっているため、お許しください ...)

$ npm i -g asciidoctor-pdf@v1.0.0-alpha.12
$ npm i -g @asciidoctor/core@2.2.1

asciidoctor-web-pdf を使用して、実際に AsciiDoc (source.adoc) から PDF (target.pdf) を生成するためのコマンドは以下になります。

$ asciidoctor-web-pdf -a stylesheet="+stylesheet.css" source.adoc target.pdf

おいおい stylesheet.css って何だよ、という声が聞こえてきそうですが asciidoctor-web-pdf はその PDF を生成する仕組みにヘッドレスブラウザ (Headless browser) を使用しているため、CSS を用いて生成内容の装飾をすることが可能です。むしろ、この CSS さえ書いてしまえばどんな報告書もたちまち「イイ感じ」になります。

AsciiDoc の記法については探せばためになる参考文献がいっぱい出てくるため、本記事では「asciidoctor-web-pdf で PDF を生成する際に留意すると良い CSS の書き方について」を述べたいと思います。また、自身で CSS をカスタマイズする際には、上記でコマンドを叩く時に PDF と同時に生成される .html ファイルの中身を見ると、どの要素にプロパティを当てると良いか参考になります。

フォント

CSS なので、Web フォントを使用することが可能です。 Google Fonts からお気に入りのフォントを探し font-family で特定の要素に当てると良いでしょう。参考までに、私が使用している CSS では以下のフォントを利用しています。

ゴシック体 : Noto Serif JP
- 主に Heading 要素などの見出しに用います。
明朝体 : Noto Sans JP
- 主に本文に用います。表紙のタイトルにも使用しています。
等幅フォント : M PLUS 1 Code
- 報告書内で、実際のコードを引用する場面があるので code や pre 要素に対して適用します。

また、フォントを列挙して指定する際に、特定の要素にだけ当たらない ... ということがあるので、その場合は個別に !important を指定すると良いでしょう。

`@page`

@page 内のアットルールおよび擬似クラスと content を用いることによって、それぞれページの済みに記載できる内容をコントロールできます。例えば、ページ右上には Confidential と機密レベルを記載したり、ページ右下にはページ番号を書いたり ... などができます。以下に、実際に用いている CSS を記載します。表示する内容の参考にしてください。また @page :left は以下に記載している @page :right と同様のため省略しています。もし左右ページで表示する内容をコントロールしたい場合は、記載内容を変えてください。

/* 表紙 */
@page :first {
  @bottom-right {
    font-size: 10pt;
    content: "ここに日付を入れる";
    margin: 0pt;
  }
}

/* 右ページ (:left は同様の表記のため省略) */
@page :right {
  /* 右上 */
  @top-right{
    content: "Confidential";
    font-size: 12pt;
    color: #ff4b00;
    margin: 10pt 0pt 0pt 0pt;
  }

  /* ページ番号 */
  @bottom-right {
    font-size: 10pt;
    content: counter(page);
    margin: 0pt;
  }

  /* 権利者表記 */
  @bottom-left {
    font-size: 10pt;
    content: "© 2022 LAC Co., Ltd.";
    margin: 0pt 0pt 10pt 0pt;
  }
}

`#cover`

表紙に付与される ID です。表紙に会社のロゴを入れたい場合は #cover { background-image: ... } で指定すると良いでしょう。また h1 にはタイトル、h2 には著者表記が入ります。

`.span`

AsciiDoc の記法で [.classname]#text# と記載すると text に .classname のクラスが適用されます。実際には <span class="classname">text</span> が生成されています。これを利用して、文字色を容易に変えることができます。

私たちが使用している CSS では赤黄青の 3色しか定義していませんが、色を増やしたい場合は以下のように定義すると良いでしょう。

また、色の定義はカラーユニバーサルデザイン推奨配色セットを参考にしています。

span.red {
  color: #ff4b00;
}

/* 以下、黄 青 も同様に指定 */
span.yellow {
  color: #f6aa00;
}

span.blue {
  color: #005aff;
}

Heading (`h2` ~ `h4`)

無くても良いのですが Heading 要素 (/=+/) 要素に下線を追記すると報告書が見やすくなるな～と思い、追加しています。また、それぞれ h2 から h4 にかけて、下線が細く、薄くなるようにしています。

h2 {
  border-bottom: solid 10px #666;
}

h3 {
  border-bottom: solid 5px #999;
}

h4 {
  border-bottom: solid 2.5px #ccc;
}

最後に

いかがでしたでしょうか。私たちが利用している CSS はもう少し他にも設定を行っていますが、割愛させていただきました。もし Word で文書を作成する際、記載内容以外で消耗している場合はこの記事のことを思い出して AsciiDoc を使っていただけると、この記事を書いた私が報われます。

「実際にどんな感じになるかサンプルが見てみたい！」という方がいらっしゃいましたら、低解像度ではありますが、私たちが提供しているサービスの「チート対策ペネトレーションテスト」のページにサンプルがありますので、ご確認ください。

また、以下に AsciiDoc の記法について参考になるリンクをいくつかご紹介します。もし表記方法に悩んだ場合は、参照するとよいでしょう。

フォント

@page

#cover

.span

Heading (h2 ~ h4)

最後に

`@page`

`#cover`

`.span`

Heading (`h2` ~ `h4`)