
정규식 규칙, 렉서 기반 의미 분석, 해시 값 매칭을 결합하여 코드 내에 노출된 자격 증명을 탐지하고 SARIF 출력을 제공하는 오프라인 시크릿 스캐너입니다.
절대 아닙니다!
LLM 열풍의 시대에도 DeepSecrets는 전적으로 여러분의 머신에서 실행됩니다 — 오프라인으로, 안전하게, 그리고 무료로 훌륭한 결과를 제공합니다.
대부분의 기존 스캐너는 실제로 코드를 "이해"하지 못합니다. 대신 텍스트만 파싱할 뿐이며 커버리지가 좋지 않습니다.
DeepSecrets는 고전적인 정규식 스캐너와 본격적인 상용 SAST 도구 사이의 간극을 메웁니다. 의미론적 코드 분석, 위험한 변수 탐지, 컨텍스트 인식 엔트로피 분석에 크게 의존함으로써 고전적인 정규식 기반 스캐닝 전략을 확장합니다. 시크릿 후보는 텍스트만이 아니라 코드가 말하는 것, 즉 이름, 할당, 호출에서 나옵니다. DeepSecrets는 약 600개 언어와 형식에 대한 렉서(Pygments)로 코드를 읽고, 14개 언어에 대한 탐지 규칙과 나머지에 대한 일반 규칙으로 변수를 찾습니다.
DeepSecrets는 또한 사전 지식 없이 자격 증명을 찾는 새로운 방법인 HashedSecret Engine을 도입합니다. 알려진 프로덕션 시크릿의 해시 값만 제공하면, 도구가 코드 내에서 평문으로 노출된 해당 시크릿을 찾아냅니다.
DeepSecrets 2.3은 SecretBench 벤치마크에서 평가되었습니다(2026년 11월): 모든 파일을 스캔하고, 레이블이 지정된 모든 행을 집계했습니다.
2026년 6월 평가가 자체 행 집합에서 집계한 방식으로 계산하면, 2.3은 94% 재현율과 85% 정밀도를 보입니다 (2026년 6월의 2.0: 93% 및 67%).
이 수치들은 레이블이 지정된 코퍼스에 대해 스캐너를 블랙박스로 실행하고 보고된 내용을 집계하는 오픈소스 벤치마크 하네스인 dsbench에서 나온 것입니다. SecretBench(저자에게 요청하여 이용 가능)와 dsbench를 사용하면 누구나 위의 행별 수치와 아래의 비교를 재현할 수 있습니다:
dsbench prepare # load SecretBench's labels and the corpus listing
dsbench run --tool-ref v2.3.0 # DeepSecrets 2.3.0 from its tag, in a venv from its own poetry.lock
dsbench tools fetch # the pinned gitleaks and Betterleaks releases, checked by SHA-256
dsbench run --tool gitleaks
dsbench run --tool betterleaks
dsbench compare RUN RUN ... # side by side, with 95% intervals
모든 실행은 각 도구의 경로 제외 설정을 끈 상태로 모든 파일을 스캔합니다. 6월 방식 수치에는 2026년 6월 평가의 행 테이블과, 라벨을 넘어선 시크릿 개수에 대한 우리의 판정 결과가 필요합니다. 둘 다 유출된 자격 증명을 가리키므로 공개되지 않았습니다.
(내부 동작 이야기와 벤치마크 분석 전체는 제 HackerNoon 기사에서 읽을 수 있습니다 여기)
pip를 통해 Github에서
$ pip install git+https://github.com/ntoskernel/deepsecrets.git
PyPi에서
$ pip install deepsecrets
DeepSecrets는 Python 3.11 이상이 필요합니다.
스캔을 실행하는 가장 쉬운 방법은 다음과 같습니다:
$ deepsecrets --target-dir /path/to/your/code --outformat dojo-sarif --outfile report.json
이 명령은 기본 구성으로 /path/to/your/code에 대해 스캔을 실행합니다:
SARIF 형식(DefectDojo 및 GitHub Security와 호환)의 보고서가 report.json에 저장됩니다.
--help 명령은 언제나 안내를 제공할 준비가 되어 있지만, 다음은 환경에 맞게 스캔을 조정하는 데 사용할 수 있는 주요 플래그입니다:
--regex-rules /path/to/rules.json: 사용자 지정 정규식 규칙 세트를 제공합니다.--hashed-values /path/to/hashes.json: 미리 해시된 알려진 프로덕션 시크릿 목록을 제공하여 안전하게 검색합니다.--excluded-paths /path/to/exclusions.json: 스캔 중 무시되는 기본 경로를 재정의하거나 확장합니다.--deep-max-size BYTES: 이 크기(기본값 250,000바이트)보다 큰 파일은 빠른 분석을 받습니다: 언어 렉서 없이 정규식 규칙과 변수 검색만 수행합니다. 큰 파일은 대부분 생성되거나 압축된 것이며, 렉서는 이런 파일에서 스캔 시간의 대부분을 차지하면서 추가로 찾아내는 것이 거의 없습니다. 0은 모든 파일에 전체 분석을 적용합니다.--skip-bundles: 다른 경로 제외에 더해 압축된 JavaScript, 소스 맵, 번들(*.min.js, *.map, *.bundle.js)을 완전히 건너뜁니다.--confidence-level {all,low,medium,high,very-high}: 보고할 최소 신뢰도(기본값 low, 모든 발견 사항). medium, high, very-high는 신뢰도 5, 6, 9 이상을 유지하며, 같은 이름의 SARIF 등급 이상에 해당하는 발견 사항입니다; all은 스캐너가 시크릿이 아니라고 판단한 정규식 일치 항목(플레이스홀더, 예제)도 -INFO 규칙 ID로 보고합니다.--min-confidence N: 신뢰도 N 이상인 발견 사항을 보고하며, N은 0에서 10 사이입니다: --confidence-level이 등급의 하한을 제공하는 반면, 이 옵션은 임의의 기준값을 지정합니다. all을 제외한 모든 레벨과 마찬가지로, 시크릿이 아니라고 판단된 정규식 일치 항목은 제외합니다. 두 플래그 중 하나만 사용하세요, 둘 다 사용하지 마세요.--exclude-tags TAG [TAG ...]: 이 태그 중 하나라도 가진 발견 사항을 제외합니다. 태그는 발견 사항이 어떤 종류의 시크릿인지 나타내며, 신뢰도는 그것이 시크릿일 가능성을 나타냅니다: weak-password(비밀번호 같은 이름 아래의 약한 값), publishable(클라이언트에 배포하기 위해 만들어진 키: reCAPTCHA 및 기타 사이트 키, Stripe pk_ 키, Mapbox pk. 토큰, 플레이어, 분석 및 지도 키), test-context(대상 디렉터리를 기준으로 한 테스트, 스펙, 픽스처, 목, 예제 또는 샘플 경로), recorded-traffic(VCR 카세트, 세션 녹화, HAR 파일), identifier(아무 권한도 부여하지 않는 사용자, 역할 또는 정책의 AWS ID), web-page(HTML 페이지). 모든 발견 사항은 기본적으로 여전히 보고됩니다; 예를 들어 실제 시크릿을 찾을 때는 --exclude-tags test-context를 사용하세요.--report-diagnostics: 대상 아래에서 발견된 모든 파일을 상태, 스캔 시간, 건너뛴 이유, 분석 깊이와 함께 SARIF 보고서에 추가합니다.--regex-candidate-scoring-rules /path/to/rules.json: 정규식 일치 항목이 보고되기 전에 판단하기 위한 사용자 지정 규칙을 제공합니다. 플래그에 값을 주지 않으면 정규식 일치 항목을 판단 없이 보고합니다.--multiprocessing-context {forkserver,spawn,fork}: 작업자 프로세스가 시작되는 방식입니다. 플랫폼이 지원하는 경우(Linux, macOS) 기본값은 forkserver입니다: 작업자는 서버 프로세스에 이미 로드된 스캐너를 공유합니다. Windows는 spawn을 사용합니다. 세 가지 모두 동일한 발견 사항을 제공합니다.--disable-masking: 출력 보고서에서 잠재적 시크릿을 마스킹하지 않고 유지합니다 (아래 주의 사항 참조).--ci / --no-ci: CI 모드를 켜거나 끕니다. CI 모드는 실시간 진행 표시 대신 30초마다 간단한 진행 줄을 출력합니다. CI 서비스(GitHub Actions, GitLab CI, Jenkins 등) 내부에서 그리고 출력이 터미널이 아닐 때마다 자동으로 켜집니다.예: .github/workflows/deepsecrets.yml
name: DeepSecrets Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.14'
- name: Install DeepSecrets
run: pip install deepsecrets
- name: Run Scan
run: deepsecrets --target-dir . --outformat dojo-sarif --outfile report.sarif
continue-on-error: true
- name: Upload SARIF report
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: report.sarif
v1.3.0부터 잠재적인 시크릿은 파이프라인 아티팩트를 보호하기 위해 보고서 내에서 자동으로 마스킹됩니다. 필요한 경우 --disable-masking 플래그를 통해 이 기능을 끌 수 있습니다.
마스킹은 보고서의 partialFingerprints 섹션이 원시 데이터를 기반으로 올바르게 채워지므로 다운스트림 플랫폼(예: Github)의 중복 제거 로직을 깨뜨리지 않습니다.
[!Caution]
마스킹을 비활성화한 상태로 DeepSecrets를 CI 파이프라인에 통합하면 CI 로그와 아티팩트 내에서 시크릿이 다시 유출될 가능성이 높습니다.
모든 발견 항목에는 신뢰도 점수가 부여됩니다. 그러나 서로 다른 보안 플랫폼은 SARIF 메트릭을 다르게 파싱합니다. 최신 ASPM 대시보드 전반에서 호환성을 보장하기 위해 DeepSecrets는 다음을 수행합니다:
가상 하위 규칙(rules[]): 신뢰도 등급별로 규칙을 동적으로 생성합니다. S105-LOW(신뢰도 04)부터 8), -MEDIUM(5), -HIGH(6S105-VERY-HIGH(9 및 10)에 이르기까지, 그리고 거부된 매치에 대해서는 --confidence-level all 보고서의 -INFO까지 생성합니다. 이를 통해 GitHub Security와 DefectDojo가 네이티브 파서를 깨뜨리지 않으면서 의미론적 정밀도 편차를 올바르게 매핑하도록 강제합니다.
결정론적 결과 레벨: 이 도구는 항상 results[] 모델에 level: error를 명시적으로 설정합니다. 이는 CI/CD 파이프라인과 구형 SAST 파서를 위한 범용 폴백 역할을 하여, 개별 규칙 해석과 관계없이 노출된 시크릿이 빌드를 안정적으로 실패시키거나 Pull Request를 차단하도록 보장합니다.
태그: 각 결과는 태그가 있는 경우 SARIF의 표준 properties.tags 배열(weak-password, publishable, test-context, recorded-traffic, identifier, web-page)에 이를 포함합니다. 규칙 ID, 심각도 및 지문은 이에 의존하지 않습니다.
맥락적 메시지: 원시 수치 신뢰도 점수를 result.message.text에 네이티브로 주입하여 보안 분석가가 대시보드에서 즉시 확인할 수 있도록 합니다.
정규식 검사용 내장 규칙셋은 /deepsecrets/rules/regexes.json에 위치합니다. 형식을 따라 사용자 정의 규칙셋을 자유롭게 생성할 수 있습니다.
해시 검사용 예제 규칙셋은 /tests/fixtures/hashed_secrets.json에 위치합니다. 형식을 따라 사용자 정의 규칙셋을 자유롭게 생성할 수 있습니다.
저장소 내에서 평문으로 노출하지 않고 알려진 프로덕션 시크릿을 찾으려면 해당 해시를 포함하는 JSON을 제공하십시오:
[
{
"name": "KNOWN-PROD-DATABASE-PASSWORD",
"hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"length": 12,
"algorithm": "sha1"
}
]
--hashed-values /path/to/hashes.json로 실행하세요. DeepSecrets는 렉싱 단계에서 문자열 후보를 즉석에서 자동으로 해시하여 일치시킵니다.
흠, 아직도 정규식 기반인가요?
그렇기도 하고 아니기도 합니다. 물론 다른 도구들처럼 타입이 지정된 시크릿을 찾기 위해 정규식을 사용합니다. 하지만 언어 이해(렉싱 단계)와 변수 탐지 역시 내부적으로 정규식을 사용합니다. 정규식은 도구일 뿐 문제가 아닙니다. 문제는 의미론적 맥락 없이 정규식을 맹목적으로 적용하는 것입니다.
그런데 Semgrep Secrets는요? 그쪽 기능을 복제하는 것처럼 보이는데요.