静的サイトのCI/CDでも侮るなかれ！Docs as Codeに沿ったセキュアな開発プロセスの実践/secure-docsascode-cicd-for-static-sites

Transcript

1. © 2024 Mizuho Research & Technologies, Ltd. 静的サイトのCI/CDでも侮るなかれ！ Docs as

   Codeに沿った セキュアな開発プロセスの実践 2024年9月21日 技術開発本部 先端技術研究部 0 ServerlessDays Tokyo 2024 （免責事項） 当レポートは情報提供のみを目的として作成されたものであり、商品の勧誘を目的 としたものではありません。本資料は、当社が信頼できると判断した各種データに 基づき作成されておりますが、その正確性、確実性を保証するものではありません。 また、本資料に記載された内容は予告なしに変更されることもあります。

2. © 2024 Mizuho Research & Technologies, Ltd. 1 自己紹介 氏名：松尾

   優成（Matsuo Yusei） 所属：先端技術研究部 兼 プロジェクト推進部 役割：社内向けAWSプラットフォームの構築・運用 社内コミュニティ「コクリエ」運営 一言：CDK が大好きです！

3. © 2024 Mizuho Research & Technologies, Ltd. 2 社内AWS共通プラットフォームの概要 •

   社内へセキュアなAWSアカウントを迅速に提供するプラットフォーム • マルチアカウント管理に AWS Control Tower と AWS CDKを活用

4. © 2024 Mizuho Research & Technologies, Ltd. 3 本プラットフォームの詳細な構成は以下で公開中！ https://aws.amazon.com/jp/builders-

   flash/202405/mizuho-service-catalog/ https://aws.amazon.com/jp/builders-flash/202406/mizuho-account-automation/ ご参考

5. © 2024 Mizuho Research & Technologies, Ltd. プラットフォームの仕様や利用方法を伝える方法は？ • やはり、ドキュメントで利用者向けにガイドすることが重要

   • 社員が気軽に参照できるよう、AWS 上で一般的な構成の静的サイトを構築 プラットフォーム初期から運営を支える重要な要素として活用！ 4 Route53 WAF CloudFront S3 ACM 社員 自社拠点 https アクセス 静的ファイルを ホスト （自社拠点の IPに制限）

6. © 2024 Mizuho Research & Technologies, Ltd. 5 話すこと ⚫

   Docs as Code の基本概念・利用ツール ⚫ ドキュメントの開発プロセス ⚫ 自動チェック・テストのプラクティス ⚫ 具体的な CI/CD パイプラインの構成・処理 AWS CDK (TypeScript)を 使用しています

7. © 2024 Mizuho Research & Technologies, Ltd. 6 Documentation as

   Code (Docs as Code)とは？ 『コーディングと同様のツールでドキュメントを作成する手法』 【特徴】 • Markdown など軽量マークアップ言語のテキストでドキュメントを記述 • Git などのバージョン管理システムでドキュメントを管理 • ドキュメントの変更はコードと同様にレビューと自動テストのプロセスを実行 Docs as Code は生産性・品質の向上につながる！

8. © 2024 Mizuho Research & Technologies, Ltd. 7 Static Site

   Generator (SSG) による HTML ファイルの生成 • Markdown を静的な HTML ファイルに変換するため、SSG が必要 • 簡単にセットアップできるシンプルな SSGとして「MkDocs」を利用 https://www.mkdocs.org/getting-started/ ・検索機能を標準装備 ・拡張機能も豊富！

9. © 2024 Mizuho Research & Technologies, Ltd. AWS リソース定義 と

   Markdown を同一リポジトリで管理 • IaC ツール「AWS CDK」で CI/CD 含む 静的サイトの AWS リソースを定義 8 Markdown + MkDocs 定義 AWS リソース 定義 Git フックで CDK ソースと 同様に Markdown も 自動チェック CDK CodePipeline CloudFront S3 ACM Route53 … CodeBuild CodeConnection …

10. © 2024 Mizuho Research & Technologies, Ltd. 9 ドキュメント開発プロセスの流れ ローカル

    ✓Markdownと 図の作成 ✓MkDocs起動/ プレビュー ✓Pre-commitで 静的解析 中央リポジトリ ✓シークレット/ コードスキャン ✓プルリク作成/ テスト実行 ✓レビュー/ マージ CI/CDパイプライン ✓各種ビルド/ テスト実行 ✓静的サイトの デプロイ ✓デプロイ後 テスト CodePipeline

11. © 2024 Mizuho Research & Technologies, Ltd. 10 ここから開発フローの 各プロセス詳細を紹介！

    まずはローカルの プロセスを解説

12. © 2024 Mizuho Research & Technologies, Ltd. 11 まずは Markdown

    でドキュメントを作成 $ mkdocs serve コマンドで サイトのローカルプレビューも可能 Markdown のサンプル HTML のサンプル ビルド 開発プロセス①「ローカル」

13. © 2024 Mizuho Research & Technologies, Ltd. ツール 特徴 主な用途

    図例 Draw.io GUIで作図 作図の融通が利き 綺麗にしやすい ・構成図 ・利用者向けの その他図 ・etc... PlantUML テキストで作図 表現に個人差が 少なく軽量で差分 など管理しやすい ・シーケンス図 ・ユースケース図 ・etc... 12 図の描画では、以下2種のツールを利用 テキストを基に レンダリング 開発プロセス①「ローカル」

14. © 2024 Mizuho Research & Technologies, Ltd. 13 textlint でテキストファイルの文章校正（Markdown,

    PlantUML） • textlint とは、各種ルールに基づいて文章校正を行う静的解析ツール • 認知負荷を低減させるため、記載揺れ設定に独自ルールを追加 PlantUMLを追加 図の表現で不都合なルールは ファイル先頭で無効化 置換ルール PlantUML (.puml) 開発プロセス①「ローカル」

15. © 2024 Mizuho Research & Technologies, Ltd. 14 husky による

    Git コミット時の自動チェック • husky とは、コミットなどの Git フックで任意コマンドを実行できるツール • textlint とその他の静的解析を自動実行することでコミット対象の品質を向上！ CDK ソースだけでなく ドキュメントも静的解析 開発者体験の観点からコミット時間に注意（不用意にコマンドを追加しない） 開発プロセス①「ローカル」 コミット前に 変更資産のみ チェック

16. © 2024 Mizuho Research & Technologies, Ltd. 15 中央リポジトリへプッシュ後のプロセスを紹介！ ローカル

    中央リポジトリ CI/CDパイプライン 次に…

17. © 2024 Mizuho Research & Technologies, Ltd. 16 GitHub の機能でセキュリティチェック

    • GitHub Advanced Security（GHAS）で 「シークレットスキャン」と「コードスキャン」を有効化 • MkDocs カスタマイズ用の JavaScript ファイルもスキャンされるので安心 機能 スキャン対象 主な検出内容 シークレット スキャン 全ファイルをチェック （Push 時） ・API キー ・アクセスキー ・パスワード ・etc... コード スキャン TypeScript・JavaScriptの コードをチェック （Push・プルリク作成時） ・command-injection ・insecure-dependency ・xss（クロスサイトスクリプティング） ・etc... 開発プロセス②「中央リポジトリ」 簡単！

18. © 2024 Mizuho Research & Technologies, Ltd. 17 Markdown のシークレットスキャン例

    開発プロセス②「中央リポジトリ」 入力例なので問題なし

19. © 2024 Mizuho Research & Technologies, Ltd. 18 プルリクエスト作成時に GitHub

    Actions で自動テスト実行 リポジトリ全体を静的解析！ ※ローカルは変更対象のみ静的解析 開発プロセス②「中央リポジトリ」 レビュワーはプルリクで 全体チェック通過を 確認できて安心！

20. © 2024 Mizuho Research & Technologies, Ltd. 19 プルリクエスト上でドキュメントのレビュー 開発プロセス②「中央リポジトリ」

    Markdown の変更差分を １つずつ確認しながら レビュー！

21. © 2024 Mizuho Research & Technologies, Ltd. 20 レビューで承認されるまではマージ禁止 開発プロセス②「中央リポジトリ」

    承認後にマージされると CI/CD パイプラインが起動

22. © 2024 Mizuho Research & Technologies, Ltd. 21 CI/CD パイプラインのプロセスを紹介！

    ローカル 中央リポジトリ CI/CDパイプライン 最後に…

23. © 2024 Mizuho Research & Technologies, Ltd. 22 CI/CD に

    CDK Pipelines を活用 開発プロセス③「CI/CD パイプライン」 パイプライン自体も 自動的に再構成 複数のパイプラインリソースを 抽象化しており導入が簡単！ https://pages.awscloud.com/rs/112-TZM-766/images/AWS-Black-Belt_2023_AWS-CDK-Basic-3-AppDev_0831_v1.pdf

24. © 2024 Mizuho Research & Technologies, Ltd. 23 開発プロセス③「CI/CD パイプライン」

    WAF [Build] [Update Pipeline] [Assets] CloudFormation デプロイ [Test] IP 制限の確認 Stack CloudFront S3 ACM Route53 … 静的サイト CDK Pipelines 起 動 プルリクエスト 静的サイトにおける CDK Pipelines 構成例 開発者 レビュワー マージ

25. © 2024 Mizuho Research & Technologies, Ltd. ビルドステージから各工程を解説！ 24 開発プロセス③「CI/CD

    パイプライン」 [Build] CDK Pipelines ビルドステージは 最も処理が多く重要な工程！

26. © 2024 Mizuho Research & Technologies, Ltd. 25 ビルドステージの流れ 開発プロセス③「CI/CD

    パイプライン」 インストール • MkDocs/ 拡張機能 • GitHub トークン設定 • 依存関係 Install (npm ci) 静的サイト ファイル生成 AWSリソース 単体テスト AWS IaC Template 生成 GitHub Packages アクセスの事前設定

27. © 2024 Mizuho Research & Technologies, Ltd. インストール 静的サイト ファイル生成

    • 社外配布用の静的 サイト zip 生成 • サイトファイル 生成(MkDocs) • TypeScript コンパイル AWSリソース 単体テスト AWS IaC Template 生成 26 ビルドステージの流れ 開発プロセス③「CI/CD パイプライン」 社内限定の静的サイト パートナー会社 社員 当社社員

28. © 2024 Mizuho Research & Technologies, Ltd. インストール 静的サイト ファイル生成

    • 社外配布用の静的 サイト zip 生成 • サイトファイル 生成(MkDocs) • TypeScript コンパイル AWSリソース 単体テスト AWS IaC Template 生成 27 ビルドステージの流れ 開発プロセス③「CI/CD パイプライン」 パートナー会社 社員 社外配布用の静的サイト セキュリティ対策として社外から SharePoint の アクセス要求が送信されるのを抑止

29. © 2024 Mizuho Research & Technologies, Ltd. 28 ビルドステージの流れ 開発プロセス③「CI/CD

    パイプライン」 インストール 静的サイト ファイル生成 • 社外配布用の静的 サイト zip 生成 • サイトファイル 生成(MkDocs) • TypeScript コンパイル AWSリソース 単体テスト AWS IaC Template 生成 $ mkdocs build $ npm run build （次工程の準備）

30. © 2024 Mizuho Research & Technologies, Ltd. 29 ビルドステージの流れ 開発プロセス③「CI/CD

    パイプライン」 インストール 静的サイト ファイル生成 AWSリソース 単体テスト • セキュリティ検証 (cdk-nag) • CDKスナップ ショットテスト • CDKアサーション テスト AWS IaC Template 生成 https://speakerdeck.com/mhrtech/secjaws32

31. © 2024 Mizuho Research & Technologies, Ltd. 30 ビルドステージの流れ テストでは生成

    AI のサポートが強力で意外と簡単！ 開発プロセス③「CI/CD パイプライン」 インストール 静的サイト ファイル生成 AWSリソース 単体テスト • セキュリティ検証 (cdk-nag) • CDKスナップ ショットテスト • CDKアサーション テスト AWS IaC Template 生成 ログ保管期間など主に 非機能の期待値チェック AWS リソースに想定外の 変更が発生していないか https://speakerdeck.com/mhrtech/cdkconjp2023

32. © 2024 Mizuho Research & Technologies, Ltd. 31 ビルドステージの流れ 開発プロセス③「CI/CD

    パイプライン」 インストール • /拡張機能 Install（pip） • GitHub Packages アクセス • 依存関係 Install ci） 静的サイト ファイル生成 AWSリソース 単体テスト AWS IaC Template 生成 • CloudFormation テンプレート生成 • アセット生成 CDK によりアセットの S3 デプロイ設定も簡単！ CDK CFn テンプレート $ cdk synth アセット (静的サイトファイルなど)

33. © 2024 Mizuho Research & Technologies, Ltd. 32 ビルドステージの流れ（全体） 開発プロセス③「CI/CD

    パイプライン」 インストール • MkDocs/拡張機能 • GitHub トークン設定 • 依存関係 Install (npm ci) 静的サイト ファイル生成 • 社外配布用の静的 サイト zip 生成 • サイトファイル 生成(MkDocs) • TypeScript コンパイル AWSリソース 単体テスト • セキュリティ検証 (cdk-nag) • CDKアサーション テスト • CDKスナップ ショットテスト AWS IaC Template 生成 • CloudFormation テンプレート生成 • アセット生成

34. © 2024 Mizuho Research & Technologies, Ltd. パイプライン自身の再構築（変更がある場合のみ） 33 開発プロセス③「CI/CD

    パイプライン」 [Update Pipeline] CDK Pipelines 具体的にはパイプライン スタックのデプロイを実行 buildspec（CDK Pipelinesで自動生成）

35. © 2024 Mizuho Research & Technologies, Ltd. アセットのアップロード 開発者は意識せず、 CDK

    Pipelines で自動実行！ 34 開発プロセス③「CI/CD パイプライン」 [Assets] CDK Pipelines HTML、CSS、JavaScript など 静的サイトのアセットをアップロード S3バケット （アセット用）

36. © 2024 Mizuho Research & Technologies, Ltd. 35 静的サイトのデプロイ 開発プロセス③「CI/CD

    パイプライン」 CloudFormation CFn テンプレートを 基にデプロイ Stack CloudFront S3 ACM Route53 … CDK Pipelines S3バケット （アセット用）

37. © 2024 Mizuho Research & Technologies, Ltd. 36 デプロイ後の IP

    制限テスト 開発プロセス③「CI/CD パイプライン」 [Test] CDK Pipelines WAF IP 制限の確認 Stack CloudFront S3 ACM Route53 … 静的サイト 共通資産として 別スタック管理 別スタックの WAF で IP 制限が無制限解放に なっていないか確認

38. © 2024 Mizuho Research & Technologies, Ltd. 37 パイプライン失敗時の通知 開発プロセス③「CI/CD

    パイプライン」 CI やデプロイなど何かしらの要因で 失敗した場合、SNS トピックに連携 インシデント…？ 通知

39. © 2024 Mizuho Research & Technologies, Ltd. 38 AWS CDK

    の補足

40. © 2024 Mizuho Research & Technologies, Ltd. 39 サーバーを意識せず、ほぼ全てを AWS

    CDK (IaC) で構築！ CDK により Lambda が自動生成されることもあり快適！ 例）S3 Object デプロイ、カスタムリソース、SSM Parameter のクロスリージョンアクセス、etc... https://www.slideshare.net/slideshow/lambdaless -and-aws-cdk-191793017/191793017 AWS CDK の補足 Lambda レスも CDK で！ https://pages.awscloud.com/rs/112-TZM-766/images/AWS-30_Serverless_AWS_Summit_JP_2024.pdf BucketDeployment で自動生成された Lambda 関数 コードは自動生成され、適切な IAM 権限も自動設定 （通常、Lambda の設定を意識する必要なし）

41. © 2024 Mizuho Research & Technologies, Ltd. 40 Docs as

    Code で重要な CI/CD も CDK Pipelines なら簡単！ https://catalog.us-east-1.prod.workshops.aws/workshops/10141411-0192-4021-afa8-2436f3c66bd8/ja-JP/2000-typescript-workshop/600-advanced-topics/700-pipelines 実機で学べて非常にオススメ！ AWS CDK の補足

42. © 2024 Mizuho Research & Technologies, Ltd. 41 CloudFront と

    S3 は CDK の便利な Construct 提供あり！ https://docs.aws.amazon.com/solutions/latest/constructs/aws-cloudfront-s3.html 静的サイトを お手軽に試せる！ AWS CDK の補足 僅か 5 行！

43. © 2024 Mizuho Research & Technologies, Ltd. 42 AWS CDK

    は学習コンテンツが豊富！ 初心者にはワークショップ・ BlackBelt シリーズが特にオススメ！ https://aws.amazon.com/jp/events /aws-event-resource/archive/ https://aws.amazon.com/jp/builders- flash/202309/awsgeek-aws-cdk/ https://catalog.workshops.aws/typescript-and-cdk- for-beginner/ja-JP https://catalog.us-east- 1.prod.workshops.aws/workshops/101414 11-0192-4021-afa8-2436f3c66bd8/ja-JP AWS CDK の補足

44. © 2024 Mizuho Research & Technologies, Ltd. 43 まとめ •

    Docs as Code の実践により AWS リソースに加えて ドキュメントの各種チェックも自動化し、生産性・品質を向上！ • 全てシフトレフトせず、DevEx も考慮してローカルチェックを策定 • AWS CDK ならサーバーを意識せずに CI/CD パイプラインと静的サイトをまとめて構築！ • セキュリティの自動化は特に重要！

45. 44