### 2. DockSecのインストール```bash
# Full install with AI analysis support (recommended)
pip install "docksec[ai]"

# Or the slim, scan-only core (no LLM dependencies, no API key needed)
pip install docksec

すべてのスキャンは結果サマリーで終了します。重大度テーブル、評価付きの0〜100のセキュリティスコア、「Quick take」アクションブロック、生成されたレポート（デフォルトでは`~/.docksec/results/`に保存）、および推奨される次のコマンドです。

### 4. AI分析を有効にする

AI分析は検出結果を説明し、修正案を提示します。プロバイダーを選択し、そのAPIキーを設定して、実行します:```bash
# OpenAI (default provider)
export OPENAI_API_KEY="sk-..."
docksec Dockerfile

# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."
docksec Dockerfile --ai-only --provider anthropic --model claude-sonnet-5

# Google Gemini
export GOOGLE_API_KEY="..."
docksec Dockerfile --ai-only --provider google

# Ollama (fully local, no API key, data never leaves your machine)
docksec Dockerfile --ai-only --provider ollama --model llama3.1

AI プロバイダーにコンテンツが送信される前に、機密に見える値（パスワード、トークン、
API キー、秘密鍵ブロック）は自動的にマスクされます。詳細は
[データフローとプライバシー](#data-flow-and-privacy) を参照してください。

### 5. またはコンテナイメージを実行する（インストール不要）

公開されているイメージには、固定バージョンの Trivy と Hadolint がバンドルされているため、
インストールも設定も不要です：```bash
docker run --rm -v "$PWD:/github/workspace" \
  -e INPUT_DOCKERFILE=Dockerfile \
  -e INPUT_SCAN_ONLY=true \
  ghcr.io/owasp/docksec:latest

このイメージは GitHub Action と同じ `INPUT_*` 変数を読み取るため、任意の Action 入力がここで機能します: `INPUT_IMAGE`、`INPUT_COMPOSE`、`INPUT_SEVERITY`、`INPUT_FAIL_ON`、`INPUT_FORMAT`、`INPUT_SARIF`、`INPUT_OUTPUT_DIR`。コンテナ終了後もレポートを保持するには、マウント上のどこかにレポートを書き込んでください:```bash
docker run --rm -v "$PWD:/github/workspace" \
  -e INPUT_COMPOSE=docker-compose.yml \
  -e INPUT_SCAN_ONLY=true \
  -e INPUT_FORMAT=json,html \
  -e INPUT_OUTPUT_DIR=/github/workspace/docksec-reports \
  ghcr.io/owasp/docksec:latest

---

## 一般的なコマンド```bash
# Scan Dockerfile + Docker image (AI + scanners)
docksec Dockerfile -i myapp:latest

# Scan a Docker Compose file and all its services
docksec --compose docker-compose.yml

# Scan only a Docker image
docksec --image-only -i myapp:latest

# Fast local scan, no AI, no API key
docksec Dockerfile --scan-only

# Choose which severity levels the image scan reports (default: CRITICAL,HIGH)
docksec -i myapp:latest --image-only --severity CRITICAL,HIGH,MEDIUM

# Fail the build (exit 1) if any finding is HIGH or above
docksec -i myapp:latest --image-only --fail-on high

# Write only the report formats you want, to a directory of your choice
docksec Dockerfile --scan-only --format json,html --output-dir ./reports

# Write a Markdown report for posting directly into a pull request comment
docksec Dockerfile --scan-only --format markdown

# Print results as JSON to stdout for scripts and CI pipelines
docksec -i myapp:latest --image-only --json

# Write a SARIF report for GitHub Code Scanning
docksec Dockerfile --scan-only --sarif

# Write a CycloneDX SBOM of an image for supply-chain tooling
docksec --image-only -i myapp:latest --sbom

# Fully offline scan: local Trivy DB, no network, no AI
docksec --image-only -i myapp:latest --offline

# Save today's findings as a baseline, then only gate on new findings later
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --update-baseline
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --fail-on high

# Suppress triaged findings with an auditable ignore file
docksec -i myapp:latest --image-only --ignore-file .docksec-ignore.yml

# Force a fresh scan, bypassing the results cache
docksec -i myapp:latest --image-only --no-cache

# Install AI-assistant skill files (Claude Code, Cursor, Copilot, and more)
docksec install-skill

# Output control
docksec Dockerfile --scan-only --quiet                  # warnings, errors, summary only
docksec Dockerfile --scan-only --verbose                # INFO-level diagnostics on stderr
docksec Dockerfile --scan-only --verbose --log-file logs/docksec.log
docksec Dockerfile --scan-only --compact-output         # shorter per-finding output
docksec Dockerfile --no-color                           # also honors NO_COLOR

# Apply the mechanical Dockerfile fixes (keeps a .bak, re-scans, shows the delta)
docksec Dockerfile --scan-only --fix --dry-run          # print the diff, change nothing
docksec Dockerfile --scan-only --fix

# Rank findings by severity alone, with no EPSS lookup and no network call
docksec Dockerfile --scan-only --no-epss

# Treat a scan that could not complete as a failure, not a pass
docksec Dockerfile --scan-only --fail-on high --incomplete-policy fail

すべての設定は任意です。省略したものは環境変数にフォールバックし、その後、組み込みのデフォルト値にフォールバックします。完全な注釈付きの例は
[`examples/.docksec.yml`](https://github.com/owasp/docksec/blob/main/examples/.docksec.yml) にあります。

### 優先順位

優先度が高い順:```
CLI flag  >  environment variable  >  .docksec.yml  >  built-in default

### 優先度: 最初に修正すべきもの

すべての CVE 検出結果は [EPSS](https://www.first.org/epss/) に対してスコアリングされます。これは、今後 30 日以内に悪用される確率を推定するものです。これを深刻度と組み合わせることで、4 つの階層が得られます:

| 階層 | 意味 |
|---|---|
| **Fix Now** | 重大または高深刻度で、かつ悪用される可能性が高い CVE の上位 10% に入るもの |
| **Fix Soon** | 重大または高深刻度だが、悪用はあまり一般的でないもの |
| **Monitor** | 深刻度は低いが、活発に悪用されているもの |
| **Low Priority** | 深刻度が低く、悪用も一般的でないもの |

これは DockSec が AI パス以外で行う唯一のネットワーク呼び出しであり、意図的に範囲を狭めています: **送信されるのは CVE ID のみ** で、イメージ名、ファイル内容、パスは送信されません。スコアは 24 時間キャッシュされます。`--offline` と `--no-epss` で無効化でき、失敗した場合はスキャンを失敗させるのではなく、深刻度のみのランキングにフォールバックします。

### エクスプロイトチェーン

サービスごとのビューでは、検出結果を 1 つずつ報告します。DockSec はまた、別々の検出結果がどのように組み合わさって単一の攻撃パスになるかも報告します:```text
Exploit chains
  [HIGH] 'web' is internet-facing and can reach 'db' with a committed credential
      services: web, db
      combines: compose-plaintext-secret-env, compose-no-network-segmentation
      'web' accepts connections from outside the host and shares the default
      network with 'db'. 'db' is not exposed directly, but its credential is in
      the compose file, so compromising 'web' yields authenticated access to it.
      Neither service looks critical on its own.
      break it: Put 'db' on its own network that 'web' does not join, or move
      POSTGRES_PASSWORD to a Docker secret.

### 機械可読出力

`--json` は、人間が読みやすいサマリーの代わりに、単一の JSON オブジェクト（スキャン情報、脆弱性、重大度カウント、および AI による検出結果）を stdout に出力するため、そのまま他のツールにパイプで渡すことができます:```bash
docksec -i myapp:latest --image-only --json | jq '.severity_counts'

> `if: always()` は重要です。これがないと、`--fail-on` によって DockSec が非ゼロで終了したときにアップロードステップがスキップされ、最も重要なときに検出結果を失ってしまいます。

### ベースライン / ラチェットモード

`--baseline FILE` を使うと、既存のプロジェクトに `--fail-on` を導入する際に、既存の検出結果の山がすべてのビルドをブロックすることを避けられます。一度 `--update-baseline` を付けて実行して現在の検出結果をスナップショットし、そのベースラインファイルをコミットします。それ以降、`--fail-on` はベースラインにまだ含まれていない検出結果のみをゲート対象とします:```bash
# Snapshot current findings (does not gate)
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --update-baseline

# Later runs only fail on NEW findings above the threshold
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --fail-on high

抑制された検出事項は、スコアリング、レポート、`--json` 出力、および `--fail-on` ゲートの前に削除されます。期限切れのエントリは自動的に適用されなくなり（警告付き）、理由のないエントリはフラグが立てられるため、waiver は監査可能な状態に保たれます。ファイルをバージョン管理にコミットして、抑制が他の変更と同様にレビューされるようにしてください。

---

## レポート

### レポート形式

デフォルトでは、すべてのスキャンで4つのレポートファイルが書き出されます。`--format` を使用してサブセットを選択できます：

- **html**: インタラクティブで視覚的にクリーンな Web レポート：重大度カード、スコア評価、修正バージョンを含む完全な脆弱性テーブル、および完全な AI 検出事項。
- **pdf**: ポータブルでプレゼンテーションに適したドキュメント。
- **json**: 完全な機械可読スキャンデータ（`--json` 標準出力と同じ形式）。
- **csv**: 個々の脆弱性を表形式でまとめたスプレッドシート対応のテーブル。
- **markdown**: 軽量で読みやすいレポート（重大度サマリー + 修正バージョンを含む脆弱性テーブル）で、プルリクエストのコメントや CI ジョブサマリーでネイティブにレンダリングされます。オプトイン：`--format` に `markdown` を追加してください。デフォルトでは書き出されません。

> CSV の動作に関する注意：脆弱性がゼロの場合でも、DockSec はヘッダーのみの
> CSV（列名のみ、行なし）を書き出します。これにより、ダウンストリームの自動化が
> ファイルの欠落や空ファイルで壊れることがありません。これは意図的な動作です。

### CycloneDX SBOM

`--sbom` は、スキャンされたイメージの CycloneDX ソフトウェア部品表（`<image>.cdx.json`）を書き出し、すべてのパッケージコンポーネントと既知の脆弱性をリストします。BOM は Trivy のネイティブエクスポーターによって生成されるため（仕様に準拠しています）、DockSec は自身をツールメタデータに刻印します。これを Dependency-Track、GitHub の依存関係グラフ、またはその他の SBOM コンシューマーに投入してください：```bash
docksec --image-only -i myapp:latest --sbom

Trivy DB が少なくとも一度ダウンロードされていることを確認してください（オンラインスキャンを一度でも実行すればダウンロードされます）。その後で `--offline` に依存するようにしてください。

### スキャン結果のキャッシュ

イメージスキャンの結果はキャッシュされ（デフォルト: 24 時間、`DOCKSEC_CACHE_TTL_HOURS` で上書き可能）、イメージのコンテンツダイジェストをキーとしているため、再利用された `:latest` のような再ビルドされたタグでも常に新しいスキャン結果が得られます。実行時にキャッシュをバイパスするには `--no-cache`（または `DOCKSEC_USE_CACHE=false`）を使用してください。

### ローカルに存在しないイメージのプル

ローカルに存在しないイメージをスキャンする場合、まずそのイメージをプルします。compose スタックは、そのマシンが一度もプルしたことのないイメージを日常的に指定しており、これがないとそれらのサービスはすべて未スキャンとして報告されます。

これを無効にして代わりに失敗させるには `DOCKSEC_PULL_MISSING_IMAGES=false` を設定してください。従量制課金の接続や共有ランナーではこれを行う価値があります。`--offline` はこの設定に関係なく、決してプルを行いません。

---

## AI アシスタント向けスキル (`install-skill`)

`docksec install-skill` は、一般的な AI コーディングアシスタント向けのよく知られたコンテキストファイルに DockSec の使用手順を書き込むため、リポジトリで作業するアシスタントが DockSec を呼び出す方法を理解できるようになります:```bash
docksec install-skill

## 検出

- **`--detect`** を指定して実行すると、検出のみが実行されます。
- 検出結果は `detections.json` に保存されます。
- 検出された各シークレットには、以下が含まれます:
  - 検出されたシークレットの種類
  - ファイルパスと行番号
  - マスクされたシークレット値
  - 検出に使用された検出器
  - 検出の信頼度

## 検証

- **`--verify`** を指定して実行すると、検出と検証の両方が実行されます。
- 検証結果は `verified.json` に保存されます。
- 検証された各シークレットには、以下が含まれます:
  - 検証済みのシークレット値
  - 検証に使用された検証器
  - 検証ステータス
  - 検証の詳細

## 出力ファイル

- **`detections.json`** — 検出されたすべてのシークレット
- **`verified.json`** — 検証されたシークレット
- **`scan.log`** — スキャンログ

## 設定

- **`--config`** を使用して、カスタム設定ファイルを指定します。
- 設定ファイルは YAML 形式である必要があります。
- 設定オプションには、以下が含まれます:
  - 除外するパス
  - 除外する検出器
  - カスタム検出器
  - カスタム検証器

## 例

```bash
# リポジトリを検出のみでスキャン
kingfisher scan --detect --repo https://github.com/example/repo.git

# リポジトリを検証付きでスキャン
kingfisher scan --verify --repo https://github.com/example/repo.git

# ローカルディレクトリを検出のみでスキャン
kingfisher scan --detect --path /path/to/directory

# ローカルディレクトリを検証付きでスキャン
kingfisher scan --verify --path /path/to/directory

# カスタム設定でスキャン
kingfisher scan --config /path/to/config.yaml --repo https://github.com/example/repo.git

これは意図的に保守的です。ベースイメージのバージョンを選択したり、シークレットを移動したり、URLを取得したりアーカイブを展開する `ADD` を変換したり、composeファイルを編集したりすることはありません。それらは代わりに「Needs review」の下で報告されます。また、`--force` が指定されない限り、未コミットの変更があるファイルの編集を拒否するため、gitは常に変更を元に戻せる状態にあります。

## ドキュメント

| ガイド | 内容 |
| --- | --- |
| [評価ガイド](https://github.com/owasp/docksec/blob/main/docs/evaluation-guide.md) | 15分間の評価。DockSecが*行わない*ことについても含む |
| [エクスプロイトチェーン](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md) | サービス間の攻撃パスとその限界 |
| [Composeルールリファレンス](https://github.com/owasp/docksec/blob/main/docs/rules/README.md) | 全17ルール: それぞれが検出する内容と、それを維持することが妥当な場合 |
| [CI統合](https://github.com/owasp/docksec/blob/main/docs/ci/README.md) | Jenkins、GitLab、Azure Pipelines、pre-commit |
| [例](https://github.com/owasp/docksec/blob/main/examples/README.md) | 10個のDockerfileとcomposeスタック、およびそれぞれの予想される検出結果 |
| [ケーススタディ](https://github.com/owasp/docksec/blob/main/docs/case-studies/README.md) | 公式イメージの実際のスキャンとその数値 |

## ロードマップ

DockSecが向かう先については [ROADMAP.md](https://github.com/owasp/docksec/blob/main/ROADMAP.md) を参照してください: ローカルDockerデーモンなしでのレジストリスキャン、リポジトリレベルのポリシー設定ファイル、Jenkins/GitLab/Azure DevOpsテンプレート、公式コンテナイメージ、KubernetesおよびHelmスキャンなど。優先順位に関するフィードバックと投票は、[issues](https://github.com/OWASP/DockSec/issues) および [OWASP Slack](https://owasp.slack.com/archives/C0APXGCUW7M) で歓迎します。

---

## コントリビューション

DockSecはコミュニティの貢献によって成り立っています。開発者、デザイナー、セキュリティ愛好家を問わず、参加する方法はたくさんあります:

- **コード貢献**: バグの修正や新機能の追加。
- **ドキュメント**: ガイドの改善やチュートリアルの作成。
- **Issue報告**: バグの特定と報告。
- **フィードバック**: 経験や提案の共有。

始めるには、[Contributing Guidelines](https://github.com/owasp/docksec/blob/main/CONTRIBUTING.md)、[Code of Conduct](https://github.com/owasp/docksec/blob/main/CODE_OF_CONDUCT.md)、[Sponsorship Guide](https://github.com/owasp/docksec/blob/main/SPONSORSHIP.md) をご覧ください。

---

## リーダーとコミュニティ

DockSecは、コンテナセキュリティをより身近にすることを使命とする専任チームによって率いられています:

- [Advait Patel](https://github.com/advaitpatel) - プロジェクトリード
- [Arkadii Yakovets](https://github.com/arkid15r) - プロジェクト共同リード

ここで見つけることができます:

- **OWASPプロジェクトページ**: [owasp.org/DockSec/](https://owasp.org/DockSec/)
- **OWASP Slack**: [#project-docksec](https://owasp.slack.com/archives/C0APXGCUW7M)
- **PyPI**: [pypi.org/project/docksec/](https://pypi.org/project/docksec/)
- **Issues**: [バグを報告](https://github.com/OWASP/DockSec/issues)
- **変更履歴**: [CHANGELOG.md](https://github.com/owasp/docksec/blob/main/CHANGELOG.md)

---

<div align="center">
  <strong>DockSecが役に立ったなら、リポジトリにスターを付けて他の人が見つけられるようにしましょう。</strong><br>
  <a href="https://github.com/advaitpatel">Advait Patel</a> とOWASPコミュニティによって構築されています。
</div>