ntoskernel/deepsecrets정규식 규칙, 렉서 기반 의미 분석, 해시 값 매칭을 결합하여 코드 내에 노출된 자격 증명을 탐지하고 SARIF 출력을 제공하는 오프라인 시크릿 스캐너입니다.
절대 아닙니다!
LLM 열풍의 시대에도 DeepSecrets는 전적으로 여러분의 머신에서 실행됩니다 — 오프라인으로, 안전하게, 그리고 무료로 훌륭한 결과를 제공합니다.
대부분의 기존 스캐너는 실제로 코드를 "이해"하지 못합니다. 대신 텍스트를 파싱할 뿐이며 커버리지도 좋지 않습니다.
DeepSecrets는 고전적인 정규식 스캐너와 본격적인 상용 SAST 도구 사이의 간극을 메웁니다. 시맨틱 코드 분석, 위험한 변수 탐지, 컨텍스트 인식 엔트로피 분석에 크게 의존하여 고전적인 정규식 기반 스캐닝 전략을 확장합니다. 즉, 시크릿 후보는 항상 의미론적으로 올바릅니다. 우리는 렉싱 및 파싱 기법을 사용하여 500개 이상의 언어와 형식에 걸쳐 진정한 코드 이해를 달성합니다.
DeepSecrets는 또한 아무런 사전 지식 없이 자격 증명을 찾는 새로운 방법인 HashedSecret Engine을 도입합니다. 알려진 프로덕션 시크릿의 해시 값만 제공하면, 도구가 코드 내에서 평문으로 노출된 해당 시크릿을 찾아냅니다.
DeepSecrets v2.0은 (2026년 6월) SecretBench 벤치마크를 대상으로 평가되어 기존의 평면 텍스트 스캐너를 능가하는 성과를 보였습니다:
(내부 동작 원리와 벤치마크 분석에 대한 전체 이야기는 제 HackerNoon 기사에서 읽어보실 수 있습니다 여기)
Github에서 pip를 통해
$ 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는 신뢰도 3, 6, 9 이상을 유지합니다; all은 스캐너가 시크릿이 아니라고 판단한 정규식 일치 항목(플레이스홀더, 예제)도 -INFO 규칙 ID와 함께 보고합니다.--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.11'
- 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부터 -MEDIUM, -HIGH를 거쳐 S105-VERY-HIGH까지(그리고 --confidence-level all이 보고하는 거부된 매치의 경우 -INFO까지) 신뢰도 등급별로 규칙을 동적으로 생성합니다. 이를 통해 네이티브 파서를 깨뜨리지 않으면서 GitHub Security와 DefectDojo가 의미론적 정밀도 편차를 올바르게 매핑하도록 강제합니다.
결정론적 결과 레벨: 이 도구는 항상 results[] 모델에 level: error를 명시적으로 설정합니다. 이는 CI/CD 파이프라인과 구형 SAST 파서를 위한 범용 폴백 역할을 하여, 개별 규칙 해석과 무관하게 노출된 시크릿이 빌드를 안정적으로 중단시키거나 Pull Request를 차단하도록 보장합니다.
맥락적 메시지: 원시 수치 신뢰도 점수를 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는요? 그쪽 기능을 복제하는 것 같은데요.
DeepSecrets는 원래 2023년 4월에 출시되었으며, 이는 Semgrep Secrets 출시보다 6개월 앞선 것입니다. 유사한 원칙을 공유하지만, DeepSecrets는 100% 무료/오픈소스이며 훨씬 더 광범위한 다국어 추적 범위를 활용합니다.
다른 도구들이 자신이 아는 것만 스캔하는 반면, DeepSecrets는 렉서를 활용합니다. 이를 통해 벤치마크에 데이터셋이 없을 수 있는 희귀한 구성 형식과 사용자 정의 코드 블록에 숨겨진 위험한 자격 증명을 찾아낼 수 있습니다.
| 기능 / 역량 | DeepSecrets 2.2 | Gitleaks | TruffleHog | Semgrep Secrets |
|---|---|---|---|---|
| SecretBench 정확도 | 93% 재현율 79% 정밀도 | 88% 재현율 46% 정밀도 | 52% 재현율 6% 정밀도 | 평가되지 않음 |
| 가격 및 라이선스 | 무료 / 오픈소스 | 무료 / 오픈소스 | 무료 / 오픈소스 | 상용 / 유료 |
| 분석 유형 | 의미론적 / 정규식 | 평문 정규식 / 엔트로피 | 평문 정규식 / 엔트로피 | 의미론적 |
| 언어 지원 | 500+ | 컨텍스트 무관 (텍스트) | 컨텍스트 무관 (텍스트) | 제한된 하위 집합 |
| 사전 해시 검증 | 예 (Hashed Engine 사용) | 아니오 | 아니오 | 아니오 |
| 컨텍스트 인식 엔트로피 | 예 (할당된 값) | 아니오 (전체 파일 텍스트) | 아니오 (전체 파일 텍스트) | 예 |
| 고급 SARIF 출력 | 예 (동적 신뢰도) | 기본 | 기본 | 예 |
진짜 추상 구문 트리를 만들지 않는 이유는 무엇인가요? 학술적으로 더 정확하지 않나요!
DeepSecrets는 복잡성과 효과성 사이의 균형을 유지하려고 합니다. 500개 이상의 언어에 걸쳐 진정한 AST를 구축하는 것은 매우 복잡하며 시크릿 탐지에는 지나친 과잉입니다. 이 도구는 코드 분석에 일반적인 SAST 접근 방식을 따르지만 최대 속도와 폭을 위해 AST 단계를 최적화합니다.
나만의 의미론적 규칙을 만들고 싶습니다. 어떻게 하나요?
의미론적 규칙은 이제 사실상 "변수 평가 규칙"입니다. 여기에서 확인할 수 있습니다.
아직 질문이 있습니다
pyproject.toml에 나열된 이메일을 사용하여 개발자에게 직접 문의하시기 바랍니다.
몇 가지 핵심 개념이 있습니다:
FileTokenizerTokenEngineFindingScanMode관리에 필요한 모든 메서드를 갖춘 파일의 파이썬식 표현입니다.
파일의 내용을 그 로직에 따라 조각(Token)으로 나눕니다. 사용 가능한 토크나이저에는 네 가지 유형이 있습니다:
FullContentTokenizer: 모든 내용을 단일 토큰으로 취급합니다. 정규식 기반 검색에 유용합니다.PerWordTokenizer: 주어진 내용을 단어와 줄바꿈으로 나눕니다.LexerTokenizer: 언어별 스마트 기능을 사용하여 코드를 의미론적으로 올바른 조각으로 나누고 각 토큰에 추가 컨텍스트를 부여합니다.CheapVarDetectorTokenizer: 의미론적 변수 탐지의 한계를 보완하기 위해 엄격한 정규식을 사용합니다.의미론적 역할, 해당 파일, 그리고 파일 내 위치에 대한 추가 정보를 담은 문자열입니다.
자체 로직에 따라 단일 토큰에 대한 시크릿 검색을 수행하는 구성 요소입니다. Finding 집합을 반환합니다. 사용 가능한 엔진에는 세 가지가 있습니다: