DockSec

AI 기반 Docker 보안 스캐너로 취약점을 평이한 영어로 설명합니다

DockSec이란 무엇인가요?

DockSec은 복잡한 보안 스캔 결과와 개발자가 실행할 수 있는 수정 사항 사이의 격차를 해소하는 OWASP Lab 프로젝트입니다. 업계 표준 스캐너(Trivy, Hadolint, Docker Scout)를 AI와 통합하여 상황에 맞는 보안 분석을 제공합니다.

200개 이상의 CVE 목록으로 사용자를 압도하는 대신, DockSec은:

• 우선순위를 매겨 실제로 특정 컨테이너 구성에 영향을 주는 항목을 골라냅니다.
• 설명합니다 - 보안 전문 용어가 아닌 이해하기 쉬운 영어로 취약점을 설명합니다.
• 제안합니다 - Dockerfile에 대한 구체적인 수정 사항을 제안합니다.
• 생성합니다 - 팀을 위한 전문적이고 인터랙티브한 보안 보고서를 생성합니다.

모든 스캔은 로컬에서 수행됩니다. 사용자의 머신을 떠나는 것은 선택한 AI 제공자에게 전송되는 (비밀 정보가 삭제된) 파일 콘텐츠뿐이며, 로컬 모델이나 스캔 전용 모드를 사용하면 아무것도 외부로 나가지 않습니다. 데이터 흐름 및 개인정보 보호를 참조하세요.

작동 방식

DockSec은 4단계 파이프라인을 따릅니다:

1. 스캔: Trivy, Hadolint, Docker Scout를 사용자 환경에서 로컬로 실행합니다.
2. 분석: AI가 모든 스캐너의 결과를 상호 비교하여 노이즈를 제거하고 실제 영향을 평가합니다.
3. 권장: 사람이 읽을 수 있는 설명과 구체적인 수정 단계를 생성합니다.
4. 보고서: 실행 가능한 결과를 HTML, PDF, JSON, CSV, SARIF 및 CycloneDX SBOM 형식으로 내보냅니다.

시작하기

1. 사전 요구 사항

DockSec은 로컬 스캐너를 오케스트레이션하므로 다음이 필요합니다:

또는 DockSec이 Trivy와 Hadolint를 대신 설치하게 할 수도 있습니다:```bash python -m docksec.setup_external_tools

3. 첫 번째 스캔 실행하기

로컬 스캔에는 API 키가 필요하지 않습니다:```bash docksec Dockerfile --scan-only

각 제공업체에는 합리적인 기본 모델이 있습니다 (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

일반 명령```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

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 --no-color # also honors NO_COLOR

모든 설정은 선택 사항이며, 생략한 항목은 환경 변수로 대체되고, 그다음에는 내장 기본값으로 대체됩니다. 주석이 포함된 전체 예제는 examples/.docksec.yml에 있습니다.

우선순위

높은 우선순위부터:``` CLI flag > environment variable > .docksec.yml > built-in default

--json만 사용하면 보고서 파일이 작성되지 않습니다. --format과 함께 사용하면 파일을 작성하는 동시에 JSON을 출력할 수 있습니다. 사람이 읽을 수 있는 모든 메시지는 --json 모드에서는 stderr로 이동하므로 stdout에는 항상 JSON 페이로드만 포함됩니다.

GitHub Code Scanning용 SARIF 출력

--sarif는 다른 보고서 형식과 함께 SARIF 2.1.0 보고서를 작성합니다. 표준 github/codeql-action/upload-sarif 액션으로 업로드하면 풀 리퀘스트와 보안 탭에서 결과가 직접 주석으로 표시됩니다:```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

검출 결과는 취약점 ID, 대상, 패키지 이름으로 매칭되므로, 관련 없는 결과가 생기고 사라져도 기준선은 유효하게 유지됩니다. 현재 상태를 새 기준선으로 수용하려면 언제든 --update-baseline 옵션으로 다시 실행하세요.

검출 결과 무시(면제)

--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"

--sbom needs a single image (-i), so it is skipped for compose runs. Like --sarif, it is independent of --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 고급 스캔을 건너t락니다. 이는 차단된(air-gapped) 또는 잠긴 환경에서 스캔하는 가장 간단한 방법입니다:```bash docksec --image-only -i myapp:latest --offline

다음을 생성하거나 업데이트합니다:

• .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를 결합합니다.
• 보안 점수: 시간에 따른 보안 상태를 추적할 수 있는 등급과 함께 0-100 점수를 제공합니다.
• 다양한 형식: HTML(대화형), PDF, JSON, CSV, SARIF 및 CycloneDX SBOM을 지원합니다.
• CI/CD 지원: --fail-on 종료 코드, 베이스라인/래칫 모드, 감사 가능한 면제, JSON-to-stdout 및 Marketplace의 GitHub Action을 지원합니다.
• 오프라인 모드: 로컬 Trivy 데이터베이스를 사용하여 완전히 분리된(air-gapped) 환경에서 스캔합니다 (--offline).
• AI 어시스턴트 스킬: docksec install-skill은 Claude Code, Cursor, Copilot 등에 저장소에서 DockSec을 실행하는 방법을 알려줍니다.

DockSec 비교

DockSec은 이들 중 상황에 맞는 Dockerfile 수정 기능과 완전한 오픈소스, OWASP 관리, 로컬 실행 가능한 설계를 결합한 유일한 도구입니다. Snyk와 Aikido는 강력한 AI 수정 기능을 제공하지만, 데이터를 자사 서비스로 전송하는 상용 클라우드 플랫폼으로만 제공됩니다. Trivy는 오픈소스이고 로컬에서 실행되지만 탐지에서 멈추며 수정을 돕지 않습니다. DockSec은 수정 가이드와 데이터에 대한 완전한 통제권을 모두 비용 없이 필요로 하는 개발자와 규제 대상 또는 분리된 환경의 팀에게 그 공백을 메워줍니다.

로드맵

DockSec의 향후 방향은 ROADMAP.md에서 확인할 수 있습니다: 로컬 Docker 데몬 없이 레지스트리 스캔, 저장소 수준 정책 구성 파일, Jenkins/GitLab/Azure DevOps 템플릿, 공식 컨테이너 이미지, Kubernetes 및 Helm 스캔 등입니다. 우선순위에 대한 피드백과 투표는 issues와 OWASP Slack에서 환영합니다.

기여

DockSec은 커뮤니티 기여로 성장합니다. 개발자, 디자이너, 보안 애호가 등 누구든 참여할 수 있는 많은 방법이 있습니다:

• 코드 기여: 버그를 수정하거나 새로운 기능을 추가합니다.
• 문서화: 가이드를 개선하거나 튜토리얼을 작성합니다.
• 이슈 보고: 버그를 식별하고 보고합니다.
• 피드백: 경험과 제안을 공유합니다.

시작하려면 기여 가이드라인, 행동 강령, 스폰서십 가이드를 확인하세요.

리더 및 커뮤니티

DockSec은 컨테이너 보안을 누구나 접근할 수 있게 만드는 데 전념하는 전담 팀이 이끌고 있습니다:

• Advait Patel - 프로젝트 리드
• Arkadii Yakovets - 프로젝트 공동 리드

여기에서 찾을 수 있습니다:

• OWASP 프로젝트 페이지: owasp.org/DockSec/
• OWASP Slack: #project-docksec
• PyPI: pypi.org/project/docksec/
• 이슈: 버그 신고
• 변경 로그: CHANGELOG.md