貢献 on DefectDojo Documentation

パーサーへの貢献

Mon, 01 Jan 0001 00:00:00 +0000

すべてのコマンドは、クローンしたdjango-DefectDojoリポジトリのルートにいることを前提としています。

前提条件

https://github.com/DefectDojo/django-DefectDojo をフォークし、ローカルにクローンしていること。
devをチェックアウトし、最新の変更に追随していること。
git checkout -b parser-nameのように、開発用の専用ブランチを作成することを推奨します。

uWSGIのホットリロード機能があるため、docker composeでのデプロイを使用するのが最も簡単です。環境をdev環境として設定します。

$ docker/setEnv.sh dev

詳細についてはDOCKER.mdを参照してください。

Dockerイメージ

ローカルでdockerイメージをビルドし、イメージへの書き込みを可能にするために、必要に応じてローカルユーザーのuidを渡します(データベースのマイグレーションファイルを扱う際に便利です)。ユーザーのuidが1000だとすると、次のようになります。

$ docker compose build --build-arg uid=1000

変更が必要なファイルは?

ファイル	用途
`dojo/tools/<parser_dir>/__init__.py`	クラス初期化用の空ファイル
`dojo/tools/<parser_dir>/parser.py`	本体部分。ここに実際のパーサーを実装します。クラス名は、アンダースコアを除いたPythonモジュール名に`Parser`を付加したものである必要があります。例: Pythonモジュール名が`dependency_check`の場合、クラス名は`DependencyCheckParser`になります。
`unittests/scans/<parser_dir>/{many_vulns,no_vuln,one_vuln}.json`	ユニットテスト用の意味のあるデータを含むサンプルファイル。最小限のセットです。
`unittests/tools/test_<parser_name>_parser.py`	パーサーのユニットテスト。
`dojo/settings/settings.dist.py`	最新のハッシュコードベースの重複排除アルゴリズムを使用したい場合
`docs/content/supported_tools/<file/api>/<parser_file>.md`	ドキュメント。必要なファイル形式の種類と、その取得方法

ファクトリコントラクト

パーサーはファクトリパターンによって動的にロードされます。パーサーが正しくロードされ、動作するためには、このコントラクトを実装する必要があります。

パーサードキュメントテンプレート

Mon, 01 Jan 0001 00:00:00 +0000

このテンプレートは、新規または既存のパーサーをドキュメント化するために作成されています。同僚のセキュリティ専門家の助けになりそうな追加情報があれば、自由に改善してください。

この.mdファイルをコピーし、GitHubリポジトリの/docs/content/supported_tools/fileに追加します。
タイトルを、新規または既存のパーサーの名前に合わせて更新します。
以下に記載されているすべてのセクションを記入します。各セクション内の説明文や例は削除してください。

ファイル形式

パーサーが受け付けるすべてのファイル形式を指定してください(例: CSV、JSON、XML)。 関連するセキュリティツールから、対応するファイル形式を作成またはエクスポートする方法の手順を含めてください。

[File Format]内の合計フィールド数

合計データフィールド数: セキュリティツールのエクスポートファイルに含まれるフィールドの総数。 パースされた合計データフィールド数: DefectDojoの検出事項にパースされたフィールドの総数。 パースされなかった合計データフィールド数: DefectDojoの検出事項にパースされなかったフィールドの総数。

以下の形式を使用して、各フィールドの簡単な説明と、それがDefectDojoのデータモデルにどのようにマッピングされるかを記載してください。 セキュリティツールのエクスポートファイルに含まれるすべてのフィールドを、出現順に記載し、パースされないフィールドがあれば明記してください。

出現順のフィールド:

Field 1 - このフィールドがどのようにマッピングされるかの説明(例: 検出事項のタイトル、エンドポイントのホストにマッピングされる)。
Field 2 - このフィールドがどのようにマッピングされる/されないかの説明。
Field 3 - このフィールドがどのようにマッピングされる/されないかの説明。
Field 4 - このフィールドがどのようにマッピングされる/されないかの説明。 (ファイル内のすべてのフィールドについて続けてください。)

フィールドマッピングの詳細

作成される各検出事項について、パーサーが特定のデータをどのようにパースするかの詳細を記載してください。例:

オープンソースのブランチ運用とリリース

Mon, 01 Jan 0001 00:00:00 +0000

定期リリース

DefectDojoチームは、以下のケイデンスを維持することを目指しています。

マイナーリリース: 毎月第1月曜日に少なくとも月1回。
パッチ/バグフィックス: 毎週月曜日にリリース。
セキュリティリリース: 深刻度に応じて、通常のケイデンスとは別に実施されます。

GitHub Actionsが正となります。リリースは半自動化されています。定期リリースの手順は以下のとおりです。

devまたはbugfixからリリースブランチを作成し、masterに対するPRを準備します(詳細) –> メンテナーがPRを検証し、手動でマージします
タグ付け、ドラフトリリースの発行、Dockerのビルド+プッシュを行います(詳細) –> メンテナーがrelease-drafterのノートを整えてリリースを公開します
ブランチを再整合させるため、masterをdevとbugfixにマージし直すPRが作成されます(詳細)

セキュリティリリース

セキュリティ問題に関連するPRは、セキュリティアドバイザリを通じて行われます。これにより、脆弱性を早期に公開することなく非公開でコードに取り組むことができます。

リリースおよびホットフィックスのモデル

図はplantUMLで作成されています。PlantUML用のWebベースエディタはhttps://www.planttext.com で見つかります。

ドキュメントの修正

Mon, 01 Jan 0001 00:00:00 +0000

ドキュメントはHugoで構築されており、Doksテーマの派生版を使用しています。

Webサイトの静的ファイルはGitHub Actionsでビルドされ、gh-pagesブランチに公開されます。

ローカルプレビューの実行方法

Hugoをインストールします。Sass/SCSSサポート付きのextended版をインストールしていることを確認してください。Hugo GitHubにはさまざまなLinuxパッケージが用意されています。
Node.jsを使用して必要なテーマをインストールします。cd docsのあとnpm installを実行します。
Docsのローカルサーバーを実行するには、cd docsでdocsフォルダに移動し、npm run devを実行してHugoの開発サーバーを起動します。ホットリロードに対応しており、サーバーの稼働中は変更したページが自動的に更新されます。
http://localhost:1313にアクセスします。

貢献ガイドライン

現段階では、ドキュメントは主にDefectDojo Proチームによって保守されていますが、コミュニティからのドキュメントへの貢献も歓迎しています。

Search機能はdocs.defectdojo.comを指す外部インデックスを使用している点にご注意ください。そのため、devにあるページはSearchで見つけることができません。代わりに、作成した新しいURLを確認するにはローカルのsitemap.xmlファイルを参照してください: http://localhost:1313/sitemap.xml
現在のドキュメントはOpen SourceとProという2つの読者層向けに書かれているため、Hugoのフロントマターに適切なラベルを含めてください。以下のようにします。

---
title: "Your great article"
audience: opensource
---

相対リンクパスは使用しないでください: [link](../your_article/)。Hugo上では技術的に「有効」であっても、ユニットテストを通過しません。

ドキュメントのユニットテスト

DefectDojoのドキュメントでは、404やその他のリンクエラーを確認するためにLycheeを使用しています。CIでは、レンダリングされたドキュメントサイトと、Djangoアプリ(テンプレートおよび設定)にハードコードされたdocs.defectdojo.comのURLの2つをチェックします。どちらも--remapを使用し、絶対パスのdocs.defectdojo.comのURLが新しくビルドされたサイトに対して解決されるようにしています。リポジトリのルートからローカルで両方を実行するには次のようにします。