### 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일 내에 해당 취약점이 악용될 확률을 추정합니다. 이를 심각도와
결합하면 네 가지 등급이 나옵니다:

| 등급 | 의미 |
|---|---|
| **즉시 수정** | 심각 또는 높음 등급이면서, 악용 가능성 기준 상위 10%에 해당하는 CVE |
| **곧 수정** | 심각 또는 높음 등급이지만, 악용이 덜 빈번함 |
| **모니터링** | 낮은 심각도이지만, 실제로 악용되고 있음 |
| **낮은 우선순위** | 낮은 심각도, 악용이 드묾 |

이는 DockSec이 AI 단계 외에 수행하는 유일한 네트워크 호출이며,
의도적으로 범위가 좁습니다: **CVE ID만 전송됩니다** - 이미지 이름, 파일 내용,
경로는 전송되지 않습니다. 점수는 24시간 동안 캐시됩니다. `--offline`과 `--no-epss`로
비활성화할 수 있으며, 어떤 실패가 발생하더라도 스캔을 실패시키는 대신 심각도만으로
순위를 매기는 방식으로 대체됩니다.

### 익스플로잇 체인

서비스별 뷰는 발견 항목을 하나씩 보고합니다. 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가 0이 아닌 코드로 종료될 때마다 업로드 단계가 건너뛰어져, 가장 중요한 순간에 결과를 잃게 됩니다.

### 베이스라인 / 래칫 모드

`--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` 게이트 이전에 제거됩니다. 만료된 항목은 자동으로 적용이 중단되며(경고와 함께), 사유가 없는 항목은 표시되어 면제가 감사 가능한 상태로 유지됩니다. 이 파일을 버전 관리에 커밋하여 다른 변경 사항과 마찬가지로 억제 사항이 검토되도록 하십시오.

---

## 보고서

### 보고서 형식

기본적으로 모든 스캔은 네 개의 보고서 파일을 작성합니다. `--format`을 사용하여 하위 집합을 선택하십시오:

- **html**: 대화형의 시각적으로 깔끔한 웹 보고서: 심각도 카드, 점수 등급, 수정 버전이 포함된 전체 취약점 표, 그리고 완전한 AI 발견 사항.
- **pdf**: 휴대 가능한 프레젠테이션용 문서.
- **json**: 완전한 기계 판독 가능 스캔 데이터(`--json` stdout 출력과 동일한 형태).
- **csv**: 개별 취약점을 스프레드시트에 바로 사용할 수 있는 표.
- **markdown**: 풀 리퀘스트 댓글과 CI 작업 요약에서 기본적으로 렌더링되는 경량의 가독성 높은 보고서(심각도 요약 + 수정 버전이 포함된 취약점 표). 선택 사항: `--format`에 `markdown`을 추가하십시오. 기본적으로 작성되지 않습니다.

> CSV 동작에 관한 참고: 취약점이 0개인 경우에도 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`)를 사용하세요.

### 로컬에 없는 이미지 가져오기

로컬에 없는 이미지를 스캔하면 먼저 해당 이미지를 가져옵니다. 컴포즈 스택은
머신이 한 번도 가져온 적 없는 이미지 이름을 일상적으로 지정하며, 이 기능이 없으면
그러한 서비스는 모두 스캔되지 않은 것으로 보고됩니다.

이 기능을 끄고 대신 실패하게 하려면 `DOCKSEC_PULL_MISSING_IMAGES=false`를
설정하세요. 종량제 연결이나 공유 러너에서는 이렇게 하는 것이 좋습니다.
`--offline`은 이 설정과 관계없이 절대 가져오지 않습니다.

---

## AI 어시스턴트 스킬 (`install-skill`)

`docksec install-skill`은 DockSec 사용 지침을 인기 있는 AI 코딩 어시스턴트의
잘 알려진 컨텍스트 파일에 기록하므로, 저장소에서 작업하는 어시스턴트가
DockSec을 호출하는 방법을 알 수 있습니다:```bash
docksec install-skill

## 감사의 말

이 프로젝트에 영감을 주고 기여해 주신 모든 분들께 감사드립니다.

## 연락처

질문, 제안 또는 협업 기회가 있으시면 다음으로 연락해 주십시오:

- **LinkedIn**: [Your LinkedIn Profile](https://linkedin.com/in/yourprofile)
- **Twitter/X**: [@YourHandle](https://twitter.com/yourhandle)
- **Email**: [email protected]

## 지원

이 프로젝트가 유용하다고 생각하시면 다음 방법으로 지원해 주실 수 있습니다:

- ⭐ GitHub에서 저장소에 별을 눌러주세요
- 🐛 버그 보고 및 기능 요청 제출
- 💡 아이디어와 피드백 공유
- 🤝 코드 또는 문서 기여
- 📢 소셜 미디어에서 프로젝트 공유

---

<div align="center">

**⭐ 이 프로젝트가 도움이 되었다면 별을 눌러주세요! ⭐**

[![GitHub stars](https://img.shields.io/github/stars/yourusername/yourrepo?style=social)](https://github.com/yourusername/yourrepo/stargazers)

</div>```text
Applied 4 change(s)
  - added --no-install-recommends on line(s) 2  [DS029]
  - converted ADD to COPY on line(s) 3  [DL3020]
  - replaced 'USER root' with 'USER appuser' on line 5  [DS002]
  - inserted a placeholder HEALTHCHECK before line 6  [DS026]

Original saved to Dockerfile.bak
Dockerfile findings: 7 -> 2 (5 resolved)