owasp/docksecAI 기반 Docker 보안 스캐너로, 취약점을 쉬운 영어로 설명합니다. OWASP 랩 프로젝트입니다.
<div align="center"> [](https://owasp.org/DockSec/) [](https://owasp.org/DockSec/) [](https://owasp.slack.com/archives/C0APXGCUW7M) [](https://github.com/OWASP/DockSec/actions) <br>[](https://www.bestpractices.dev/projects/12939) [](https://github.com/OWASP/DockSec/blob/main/LICENSE) [](https://github.com/OWASP/DockSec/commits/main/) [](https://github.com/OWASP/DockSec/graphs/contributors) [](https://github.com/OWASP/DockSec/network/members) [](https://github.com/OWASP/DockSec/stargazers)  [](https://github.com/OWASP/DockSec/issues) [](https://github.com/OWASP/DockSec/pulls) [](https://github.com/OWASP/DockSec/commit/80664db8935e4b5ab44df5867913e) <picture> <source srcset="https://raw.githubusercontent.com/OWASP/DockSec/main/images/docksec-logo-for-github.png" media="(prefers-color-scheme: dark)"> <img src="https://assets.kitploit.com/production/public/readmes/39487/d30ee74abf3ad22a447ed36ba3010acab606147bc21702a1fb428b8633298caf.png" alt="DockSec Logo" width="600"> </picture><br> <img src="https://assets.kitploit.com/production/public/readmes/39487/009ae678c48ab2738e17c17c238c83cb2481510fbc2bf9d7284ea80ec487feda.png" alt="OWASP Logo" width="300"> # [DockSec](https://owasp.org/DockSec/) **취약점을 쉬운 말로 설명해 주는 AI 기반 Docker 보안 스캐너** </div> --- ## DockSec이란? DockSec은 복잡한 보안 스캔 결과와 개발자가 실제로 적용할 수 있는 수정 사항 사이의 간극을 메우는 **OWASP Lab 프로젝트**입니다. 업계 표준 스캐너(Trivy, Hadolint, Docker Scout)를 AI와 통합하여 **상황을 인식한 보안 분석**을 제공합니다. 200개 이상의 CVE 목록으로 압도하는 대신, DockSec은 다음과 같이 동작합니다: - 특정 컨테이너 구성에 실제로 영향을 미치는 항목을 **우선순위로 정렬**합니다. - 보안 전문 용어가 아닌 쉬운 말로 취약점을 **설명**합니다. - Dockerfile에 대한 구체적인 수정 사항을 **제안**합니다. - 팀을 위한 전문적이고 인터랙티브한 보안 보고서를 **생성**합니다. 모든 스캔은 로컬에서 수행되며, 사용자의 머신을 벗어나는 것은 사용자가 선택한 AI 제공자에게 전송되는 (비밀이 마스킹된) 파일 내용뿐입니다. 로컬 모델이나 스캔 전용 모드를 사용하면 아무것도 외부로 나가지 않습니다. [데이터 흐름과 프라이버시](#data-flow-and-privacy)를 참고하세요. --- ## 동작 방식 <div align="center"> <img src="https://assets.kitploit.com/production/public/readmes/39487/99b4247f599cc8f7a260f285815f8793ca4d2c050ea6656480818a846d590fb0.png" alt="DockSec Workflow" width="800"> <p><em>DockSec 워크플로: 스캔부터 실행 가능한 인사이트까지</em></p> </div> DockSec은 다섯 단계의 파이프라인을 따릅니다: 1. **스캔**: 사용자 환경에서 Trivy(이미지 취약점 및 Dockerfile 잘못된 구성), Hadolint, Docker Scout를 로컬로 실행합니다. 2. **우선순위 지정**: 모든 CVE 발견 항목을 심각도와 [EPSS](https://www.first.org/epss/) 악용 가능성을 결합하여 순위를 매기므로, 발견된 순서가 아니라 먼저 수정해야 할 항목 순서로 목록이 정렬됩니다. 3. **상관 분석**: 개별 발견 항목들이 결합하여 하나의 공격 경로를 이루는 [익스플로잇 체인](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md)을 탐지합니다. 인터넷에 노출된 서비스가 접근할 수 있는 자격 증명이 있는 데이터베이스는 서로 무관한 두 개의 발견 항목이 아니라 하나의 체인입니다. API 키가 있으면 AI가 전체 스캔 출력을 추론하여 이를 순위 매기고, 설명하고, 확장합니다. 4. **권장 사항 제시**: 복사해서 실행할 수 있는 수정 명령과 구체적인 Dockerfile 또는 compose 변경 사항을 생성하고, 그것이 해결하는 발견 항목 수를 명시합니다. 5. **보고서 작성**: 실행 가능한 결과를 HTML, PDF, JSON, CSV, Markdown, SARIF, CycloneDX SBOM으로 내보냅니다. --- ## 시작하기 ### 1. 사전 요구 사항 DockSec은 로컬 스캐너를 오케스트레이션하므로 다음이 필요합니다: | 요구 사항 | 필요한 용도 | 설치 | |---|---|---| | Python 3.12+ | DockSec 자체 | [python.org](https://www.python.org/downloads/) | | Trivy | 모든 스캔(필수) | `brew install trivy` 또는 [Trivy 문서](https://trivy.dev/latest/getting-started/installation/) | | Hadolint | Dockerfile 린팅 | `brew install hadolint` 또는 [Hadolint 문서](https://github.com/hadolint/hadolint#install) | | Docker | 이미지 스캔(`-i`) | [Docker 문서](https://docs.docker.com/get-docker/) | 또는 DockSec이 Trivy와 Hadolint를 대신 설치하도록 할 수 있습니다:```bash python -m docksec.setup_external_tools ``` ### 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 ``` ### 3. 첫 스캔 실행하기 로컬 스캔에는 API 키가 필요하지 않습니다:```bash docksec Dockerfile --scan-only ``` 모든 스캔은 결과 요약으로 끝납니다: 심각도 테이블, 등급이 포함된 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 ``` 각 제공자는 합리적인 기본 모델을 가지고 있으므로(OpenAI: `gpt-4o`, Anthropic: `claude-haiku-4-5`, Google: `gemini-1.5-pro`, Ollama: `llama3.1`), `--model`은 선택 사항입니다. 플래그를 반복하지 않으려면 환경 변수를 설정하거나(또는 실행하는 디렉터리의 `.env` 파일에 넣으세요 - DockSec가 자동으로 로드합니다):```bash export LLM_PROVIDER=anthropic export LLM_MODEL=claude-sonnet-5 docksec Dockerfile ``` 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 ``` 매 릴리스마다 멀티 아키텍처(amd64 및 arm64)로 게시됩니다. CI에서는 `latest` 대신 특정 버전(`ghcr.io/owasp/docksec:2026.9.21`)이나 마이너 시리즈(`ghcr.io/owasp/docksec:2026.9`)에 고정하세요. 모든 이미지에는 빌드 출처 증명이 포함되어 있습니다:```bash gh attestation verify oci://ghcr.io/owasp/docksec:latest --repo OWASP/DockSec ``` 이 이미지는 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 ``` ### 6. 또는 GitHub Action 사용```yaml - name: Run DockSec AI Scanner uses: OWASP/[email protected] with: dockerfile: 'Dockerfile' openai_api_key: ${{ secrets.OPENAI_API_KEY }} ``` ## 일반 명령어```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 ``` --- ## 구성 파일 저장소 루트에 `.docksec.yml`을 커밋하면 팀 전체와 모든 CI 작업이 동일한 정책으로 스캔하며, 각 개발자가 자신만의 플래그를 전달할 필요가 없습니다.```yaml # yaml-language-server: $schema=https://owasp.org/DockSec/docksec-config-schema.json severity: CRITICAL,HIGH fail_on: HIGH formats: [json, html] output_dir: ./security-reports rules: disabled: - compose-missing-healthcheck ``` 모든 설정은 선택 사항이며, 생략한 항목은 환경 변수로 대체되고 그다음 내장 기본값으로 대체됩니다. 전체 주석이 달린 예시는 [`examples/.docksec.yml`](https://github.com/owasp/docksec/blob/main/examples/.docksec.yml)에 있습니다. ### 우선순위 가장 높은 우선순위부터:``` CLI flag > environment variable > .docksec.yml > built-in default ``` 커밋된 `severity: LOW`는 명령줄의 `--severity CRITICAL`과 환경의 `DOCKSEC_DEFAULT_SEVERITY`에 의해 여전히 재정의됩니다. ### 검색 DockSec은 작업 디렉터리에서 `.docksec.yml`(또는 `.docksec.yaml`)을 찾은 다음 저장소 루트까지 상위로 탐색하므로, 모노레포 하위 디렉터리의 서비스는 최상위에 커밋된 정책을 상속받습니다. 검색은 `.git`이 포함된 디렉터리에서 멈추므로 저장소 외부의 파일을 가져오는 일은 없습니다. - `--config FILE`은 검색 대신 특정 파일을 사용합니다. - `--no-config`는 모든 구성 파일을 무시하여 재현 가능한 CI 실행을 보장합니다. 적용 중인 구성 파일은 스캔 배너에 표시되므로 어떤 정책이 적용되었는지 항상 명확합니다. ### 설정 | 설정 | 대응 플래그 | 비고 | | --- | --- | --- | | `severity` | `--severity` | 이미지 스캔의 심각도 수준 | | `fail_on` | `--fail-on` | CI 게이트 임계값 | | `formats` | `--format` | 목록 형식: `[json, html]` | | `output_dir` | `--output-dir` | 보고서 저장 위치 | | `provider` | `--provider` | `openai`, `anthropic`, `google`, `ollama` | | `model` | `--model` | 공급자의 모델 이름 | | `offline` | `--offline` | 네트워크 없음; AI와 Docker Scout를 건너뜀 | | `skip_ai_scoring` | `--skip-ai-scoring` | 더 이상 사용되지 않고 무시됨; 점수 산정은 항상 결정적임 | | `no_redact` | `--no-redact` | AI 호출 전에 비밀을 마스킹하지 않음 | | `no_cache` | `--no-cache` | 스캔 캐시 우회 | | `ignore_file` | `--ignore-file` | 면제 파일 경로 | | `baseline` | `--baseline` | 기준선 파일 경로 | | `rules.disabled` | - | 완전히 비활성화할 규칙 ID | 잘못된 구성 파일(알 수 없는 키, 잘못된 심각도)은 경고가 아니라 `2`로 종료되는 하드 오류입니다. 따라서 손상된 정책 파일로 인해 팀이 커밋하지 않은 규칙으로 스캔이 실행되는 일은 결코 없습니다. ### 편집기 자동 완성 첫 줄의 `# yaml-language-server:` 주석은 VS Code와 JetBrains 편집기에서 자동 완성과 인라인 유효성 검사를 제공합니다. 스키마는 [`docs/docksec-config-schema.json`](https://github.com/owasp/docksec/blob/main/docs/docksec-config-schema.json)에 게시되어 있으며 `docksec --print-config-schema`로 재생성할 수 있습니다. ### 규칙 비활성화 `rules.disabled`는 검사를 모든 곳에서 완전히 비활성화합니다. 이는 점수 산정, 보고서, `--json`, `--fail-on` 게이트 이전에 제거됩니다. 환경에 적용되지 않는 검사에 사용하세요. 팀이 분류하고 수용한 개별 발견 사항에는 사유와 만료일이 포함되어 감사 가능성을 유지하는 [면제 파일](#ignoring-findings-waivers)을 사용하는 것이 좋습니다. --- ## CI/CD 통합 ### 종료 코드 DockSec은 빌드와 셸이 결과에 반응할 수 있도록 CI 친화적인 종료 코드를 사용합니다: | 코드 | 의미 | |---|---| | `0` | 성공, `--fail-on` 이상의 발견 사항 없음 | | `1` | `--fail-on` 임계값 이상의 발견 사항 | | `2` | 사용법 또는 인수 오류 | | `3` | 도구 또는 런타임 오류 (스캔 실패, 이미지 없음, 도구 누락) | `--fail-on`은 모든 구조화된 발견 사항(이미지 취약점, Dockerfile 잘못된 구성, compose 잘못된 구성)을 게이트합니다. `--fail-on`이 요청된 `--severity`보다 낮으면 게이트가 해당 발견 사항을 관찰할 수 있도록 스캔 심각도가 자동으로 확대됩니다. ### 불완전한 스캔 스캐너를 실행할 수 없으면 결과에 발견 사항이 누락될 수 있으며, 이는 실제로 깨끗한 것이 아닙니다. DockSec은 이를 Coverage 블록과 `--json`의 `scan_info.completeness` 아래에 탐지 격차로 보고합니다. 이 경우 `--incomplete-policy fail`을 사용하여 `3`으로 종료하면 CI가 완료되지 않은 스캔을 통과할 수 없습니다:```bash docksec Dockerfile --incomplete-policy fail ``` ### 우선순위: 무엇을 먼저 수정할 것인가 모든 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. ``` 체인 탐지는 규칙 기반이므로 `--scan-only`와 함께, 오프라인에서, API 키 없이도 작동하며 매 실행마다 동일한 답을 반환한다. AI 패스는 이를 대체하는 것이 아니라 순위를 매기고 확장한다. 체인은 `--json`에서도 `exploit_chains` 아래에 나타난다. 전체 목록은 [익스플로잇 체인 가이드](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md)를, 체인이 결합하는 모든 규칙은 [compose 규칙 레퍼런스](https://github.com/owasp/docksec/blob/main/docs/rules/README.md)를 참조하라. ### 수정 명령 스캔은 식별자 목록이 아니라 구체적인 명령으로 끝나며, 해당 명령이 해결하는 발견 항목의 개수를 명확히 밝힌다:```text Fix commands > apt-get install --only-upgrade -y libgnutls30=3.7.9-2+deb12u7 CRITICAL - 3.7.9-2+deb12u4 -> 3.7.9-2+deb12u7 (CVE-2026-33845 +6) Dockerfile changes - [CRITICAL] Move the secret out of ENV; inject it at runtime (line 4) - [HIGH] Add a non-root USER before CMD/ENTRYPOINT (line 7) Applying all of the above resolves 37 of 93 finding(s); 56 have no mechanical fix yet. ``` ### 기계 판독 가능 출력 `--json`은 사람이 읽을 수 있는 요약 대신 단일 JSON 객체(스캔 정보, 취약점, 심각도 개수, 그리고 모든 AI 발견 사항)를 stdout에 출력하므로, 다른 도구로 바로 파이프할 수 있습니다:```bash docksec -i myapp:latest --image-only --json | jq '.severity_counts' ``` `--json`만 단독으로 사용하면 보고서 파일이 작성되지 않습니다. 같은 실행에서 파일을 작성하고 JSON을 출력하려면 `--format`과 함께 사용하세요. `--json` 모드에서는 모든 사람이 읽을 수 있는 메시지가 stderr로 이동하므로, stdout에는 JSON 페이로드만 포함됩니다. ### 보고서 형식 `--format`은 쉼표로 구분된 파일 출력 목록을 받습니다: | 형식 | 결과물 | |--------|----------------| | `json` | 스캔 메타데이터, 심각도 집계, 전체 취약점 목록이 담긴 `.json` 파일 (`--json` stdout 페이로드와 동일한 구조이지만 디스크에 기록됨). | | `csv` | 발견 사항의 `.csv` 테이블 (ID, 심각도, 패키지, 버전, 제목 및 관련 필드). | | `pdf` | 스캔 정보, 점수, 취약점 세부 정보가 포함된 인쇄 가능한 PDF 요약. | | `html` | 브라우저에서 결과를 탐색할 수 있는 스타일이 적용된 HTML 보고서. | | `markdown` | 풀 리퀘스트 댓글과 CI 작업 요약에서 기본적으로 렌더링되는 `.md` 보고서. 옵트인: 요청하지 않으면 작성되지 않음. | `json`, `csv`, `pdf`, `html`은 기본적으로 작성되며, `markdown`은 명시적으로 추가해야 생성됩니다. **발견 사항이 없는 경우의 CSV:** 스캔에서 취약점이 보고되지 않았지만 `--format` 목록에 `csv`가 포함되어 있으면, DockSec은 여전히 열 헤더만 포함된 CSV 파일을 작성합니다. 이는 의도된 동작입니다(내보내기가 유효하며 쓰기 실패가 아님). 따라서 다운스트림 도구는 깨끗한 스캔에서도 안정적인 스키마에 의존할 수 있습니다. stdout JSON 및 다른 도구로의 파이핑에 대해서는 위의 [기계 판독 가능 출력](#machine-readable-output)을 참조하세요. CI 및 GitHub Code Scanning에는 `--sarif`를 사용하세요(다음 섹션 참조). SARIF는 `--format`과 별개이며 요청 시 항상 출력됩니다. ### GitHub Code Scanning을 위한 SARIF 출력 `--sarif`는 다른 보고서 형식과 함께 SARIF 2.1.0 보고서를 작성합니다. 표준 `github/codeql-action/upload-sarif` 액션으로 업로드하면 풀 리퀘스트와 Security 탭에서 발견 사항이 직접 주석으로 표시됩니다:```yaml - name: Run DockSec uses: OWASP/[email protected] with: dockerfile: 'Dockerfile' sarif: 'true' - name: Upload SARIF to GitHub Code Scanning uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: ~/.docksec/results ``` > `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 ``` 취약점 ID, 대상, 패키지 이름으로 결과를 매칭하므로 관련 없는 결과가 생기고 사라져도 베이스라인이 유효하게 유지됩니다. 현재 상태를 새 베이스라인으로 수용하려면 `--update-baseline`으로 다시 실행하세요. ### 결과 무시하기 (waivers) `--ignore-file FILE`은 팀이 검토하고 수용한 개별 결과를 억제합니다. 베이스라인(특정 시점의 스냅샷)과 달리, 무시 파일은 각 항목에 사유와 선택적 만료일이 포함된 명시적이고 검토 가능한 목록입니다. 현재 디렉터리에 `.docksec-ignore.yml` 파일이 있으면 자동으로 인식됩니다.```yaml # .docksec-ignore.yml ignores: - id: CVE-2023-45853 # Trivy vulnerability ID or DockSec rule ID reason: "zlib CVE; code path not reachable, vendor fix pending" expires: 2026-12-31 # optional; entry stops applying after this date - id: compose-missing-healthcheck reason: "healthchecks are handled by the orchestrator" ``` 억제된 발견 사항은 점수 산정, 보고서, `--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 ``` `--sbom`은 단일 이미지(`-i`)가 필요하므로 compose 실행에서는 건너뜁니다. `--sarif`와 마찬가지로 `--format`과는 독립적입니다. --- ## 데이터 흐름 및 프라이버시 DockSec은 여러분의 머신을 떠나는 것이 무엇인지 항상 알 수 있도록 설계되었습니다: - **스캔은 완전히 로컬에서 수행됩니다.** Trivy, Hadolint, 보안 점수는 여러분의 머신에서 실행됩니다. 이미지 내용은 DockSec에 의해 어디에도 업로드되지 않습니다. - **AI 분석은 스캔된 파일만 전송합니다.** AI 단계가 실행되면 Dockerfile 또는 compose 파일 내용(그리고 점수 산정을 위한 취약점 개수 요약)이 여러분이 설정한 LLM 제공자에게 전송됩니다. 그 외에는 아무것도 전송되지 않습니다. - **시크릿은 전송 전에 마스킹됩니다.** 파일 내 시크릿으로 보이는 값(비밀번호, 토큰, API 키, 개인 키 블록)은 내용이 AI 제공자에게 전송되기 전에 마스킹됩니다. 키 이름은 그대로 노출되어 노출된 자격 증명이 여전히 플래그됩니다. 옵트아웃하려면 `--no-redact`를 사용하세요. - **완전 로컬 AI가 지원됩니다.** `--provider ollama`를 사용하여 AI 분석을 여러분의 하드웨어에서 유지하거나, `--scan-only` / `--offline`로 AI를 완전히 건너뛸 수 있습니다. - **텔레메트리 없음.** DockSec은 사용 데이터를 수집하지 않으며 어디에도 연결하지 않습니다. ### 오프라인 모드 `--offline`은 네트워크 접근 없이 스캔을 실행합니다. 디스크에 이미 있는 Trivy 취약점 데이터베이스를 사용하며(DB 업데이트 없음), 네트워크가 필요한 AI 분석과 Docker Scout 고급 스캔을 건너뜁니다. 에어갭 또는 폐쇄된 환경에서 스캔하는 가장 간단한 방법입니다:```bash docksec --image-only -i myapp:latest --offline ``` 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 ``` 다음을 생성하거나 업데이트합니다: - `.claude/commands/docksec.md` (Claude Code 슬래시 명령 `/docksec`) - `.cursor/rules/docksec.mdc` (Cursor) - `AGENTS.md` (Codex CLI), `GEMINI.md` (Gemini CLI) - `.github/copilot-instructions.md` (GitHub Copilot) 이 파일들은 검토하고 커밋할 수 있는 일반 텍스트이며, 아무것도 실행되지 않습니다. 명령을 다시 실행하면 DockSec 섹션이 중복되지 않고 제자리에서 업데이트됩니다. --- ## 기능 - **스마트 분석**: AI가 취약점이 *귀하의* 특정 설정에 어떤 의미인지 설명합니다. - **멀티 LLM 지원**: OpenAI, Anthropic Claude, Google Gemini 또는 Ollama를 통한 로컬 모델. - **프라이버시 우선**: 어떤 콘텐츠가 AI 제공업체에 도달하기 전에 비밀 값이 삭제되며, 스캔은 완전히 로컬에서 이루어지고, 텔레메트리가 없습니다. - **Docker Compose 스캔**: 오케스트레이션 수준의 잘못된 구성을 감지하고 compose 파일의 모든 서비스를 스캔합니다. - **심층 통합**: Trivy(취약점), Hadolint(린팅), Docker Scout를 결합합니다. --- [Read more](https://github.com/owasp/docksec)
