REST API 静的セキュリティテストアクションは、OpenAPI Specification（OAS、旧称 Swagger）に準拠した REST API コントラクトをリポジトリ内から探し出し、それらに対して徹底的なセキュリティチェックを実行します。OAS v2 と v3.0.x の両方をサポートしており、JSON 形式と YAML 形式の両方に対応しています。
このアクションは、次のようなシナリオで利用できます。
このアクションは、42Crunch API Security Audit を基盤としています。Security Audit は、API 定義の静的解析を実行し、認証・認可・データ制約に関連するベストプラクティスと潜在的な脆弱性について 300 以上のチェックを行います。
デフォルトでは、このアクションは次の処理を行います。
.json ファイルと .yaml ファイルを探します。これにより、リポジトリ内の新規または変更された API コントラクトを特定できます。
API の検出に含める／除外するリポジトリの特定部分やファイル名マスクを指定することで、アクションの動作を細かく調整できます。また、検出を完全に無効にし、チェックする特定の API ファイルだけを列挙して、42Crunch API Security Platform 上の既存 API にマッピングすることもできます。これらの設定はすべて、設定ファイル 42c-conf.yaml で構成します。高度な例については、こちらを参照してください。
検出されたすべての API は、42Crunch Platform の API コレクションにアップロードされます。デフォルトでは、このアクションは環境変数 GITHUB_REPOSITORY と GITHUB_REF を使用して、API コレクションの出自であるリポジトリとブランチ／タグ／PR 名を命名します。default-collection-name アクションパラメータを使用して名前を上書きできます。以降の実行では、コレクション内の API はリポジトリの変更と同期されます。
このアクションを GitHub の CI/CD ワークフローに追加し、セキュリティ問題を含む API 定義で失敗するように設定します。
Security Audit は、各 API コントラクトに、API のセキュリティ面を反映した 0 から 100 までの監査スコアを付けます。GitHub Action の min-score パラメータを使用して、アクションが失敗する監査スコアのしきい値を設定できます（他の値が指定されていない場合のデフォルトは 75）。これにより、品質の低い API 定義を早期に発見し、設計段階のできるだけ早い時点で問題に対処できます。
より高度な失敗条件は、設定ファイル 42c-conf.yaml で設定できます。たとえば、カテゴリ別（セキュリティまたはデータ検証）の監査スコア、問題の重大度レベル、さらには問題 ID で指定された特定の問題などです。高度な例については、こちらを参照してください。
さらに、このプラグインはプラットフォームレベルで定義された セキュリティ品質ゲート（デフォルトまたはタグ駆動）を強制します。セキュリティ品質ゲートは、企業内で定義されたアプリケーションセキュリティ要件を強制します。
アクションが実行されるたびに、各 OpenAPI ファイルの詳細な優先順位付き実用レポートへのリンクが含まれます。
リンクをたどって、42Crunch Platform で詳細レポートを読んでください。
42Crunch 監査で見つかった問題を、GitHub の Security タブの Code scanning alerts で直接追跡することもできます。
これを有効にするには、GitHub ワークフローのアクションパラメータに upload-to-code-scanning:true を含めるだけです。
いずれかのアラートをクリックすると、コード内の正確な場所を確認でき、脆弱性の詳細と推奨される修復手順を取得できます。
このアクションは、42Crunch API Security Audit サービスを使用します。アクションを使用する前に、42Crunch プラットフォームのアカウントが必要です。42Crunch の顧客でない場合は、次のページから無料アカウントをリクエストできます: https://42crunch.com/get-started/。
次に、ドキュメントに記載されている手順に従って、アクションが 42Crunch Platform に認証するための API トークンを作成し、それを GitHub のシークレットとして保存します。
api-token必須 GitHub アクションが 42Crunch Platform への認証に使用する API トークン。API トークンをワークフローファイルに直接記述しないでください。代わりに、リポジトリ設定で GitHub シークレットを作成し、以下の例のように参照してください。
min-scoreOpenAPI ファイルが到達しなければならない最小監査スコア。このスコアに達しない場合、アクションは失敗します。デフォルトは 75 です。
upload-to-code-scanning監査結果を GitHub Code Scanning にアップロードします。デフォルトは false です。このステップを成功させるには、ワークフローに特定の権限が必要であることに注意してください。
...
jobs:
run_42c_audit:
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
...
ignore-failurestrue に設定すると、設定した失敗条件（min-score や SQG 基準など）が満たされた場合でも、実行を成功として完了させます。デフォルトは false です。
このパラメータは、SQG の失敗シナリオを強制せずに検出したい場合（つまり、ビルドを壊し始める前に開発チームに猶予期間を与えたい場合）に役立ちます。
ignore-network-errorstrue に設定すると、ネットワークエラー（42Crunch Platform への接続失敗など）が発生した場合でも、実行を成功として完了させます。デフォルトは false です。
skip-local-checkstrue に設定すると、42c-conf.yaml ファイルに設定されたすべての失敗条件（最小スコアなど）が無効になり、SQG で定義された基準が満たされない場合にのみ実行が失敗します。デフォルトは false です。
platform-url42Crunch Platform にアクセスするための URL。デフォルトは https://us.42crunch.cloud です。
エンタープライズ顧客の場合は、本番プラットフォームへのアクセスに使用する URL を入力します。
root-directory42c-conf.yaml 設定ファイルを含むルートディレクトリ。指定しない場合、プラグインの現在の作業ディレクトリが使用されます。これは通常、チェックアウトされたリポジトリのルートに対応します。
default-collection-name検出された API のコレクションを作成するときに使用されるデフォルトのコレクション名。名前が指定されていない場合、リポジトリとブランチ／PR 情報からデフォルト名が作成されます。
log-levelログの詳細レベル。次のいずれか: FATAL、ERROR、WARN、INFO、DEBUG。デフォルトは INFO です。
share-everyoneCI/CD タスクによって作成された API コレクションを、42Crunch Platform 上の組織内の全員と自動的に共有します。指定できる値は、OFF、READ_ONLY、READ_WRITE です。デフォルトは OFF です。アクションが実行される ID（API トークンの所有者）に Share with Everyone 権限が必要です。ない場合、タスクは 403 エラーで失敗します。
json-report監査実行レポートを JSON 形式で指定したファイルに書き込みます。実行レポートには、作成、更新、削除された API のリストが詳しく記載されています。これは、後続のパイプラインステップで監査実行の結果を自動的に消費したい場合に役立ちます。デフォルトでは、レポートは書き込まれません。
api-tagsCI/CD タスクは、新しく作成された API にタグを自動的に割り当てることができます。タグは次の形式で指定します: category1:name1 category2:name2。このフラグは オプション です。
sarif-report監査の生の JSON 形式を SARIF に変換し、結果を指定したファイルに保存します。デフォルトでは、レポートは書き込まれません。
audit-timeout監査レポートの最大タイムアウト（秒）を設定します。この時間内に結果の準備が整わない場合、タスクは失敗します。デフォルト: 600
42Crunch Platform で API トークンを作成し、その値を API_TOKEN という名前のリポジトリシークレットにコピーします。
既存のワークフローに追加する典型的な新しいステップは、次のようになります。
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
リポジトリの内容をチェックし、プロジェクト内で見つかった各 OpenAPI ファイルに対して Security Audit を実行し、実行ファイルをアーティファクトとして保存する典型的なワークフローは、次のようになります。
name: "42crunch-audit-workflow"
# follow standard Code Scanning triggers
on:
push:
branches: [ "main" ]
pull_request:
# The branches below must be a subset of the branches above
branches: [ "main" ]
schedule:
- cron: '19 9 * * 6'
env:
PLATFORM_URL: https://us.42crunch.cloud
jobs:
run_42c_audit:
environment: QA
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
runs-on: ubuntu-latest
steps:
- name: checkout repo
uses: actions/checkout@v3
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
platform-url: ${{ env.PLATFORM_URL}}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
# Upload results to Github code scanning
upload-to-code-scanning: false
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
- name: save-audit-report
if: always()
uses: actions/upload-artifact@v3
with:
name: auditaction-report-${{ github.run_id }}
path: audit-action-report-${{ github.run_id }}.json
if-no-files-found: error
このアクションは 42Crunch Ecosystems チームによって保守されています。問題が発生した場合、またはここに記載されていない質問がある場合は、support.42crunch.com でサポートチケットを作成できます。
問題を報告する際は、必ず以下を含めてください。