nanda-rani/safe연구 산출물을 위한 맥락 기반 보안 감사 시스템
SAFE는 연구 산출물에서 Semgrep 및 Trivy 발견 사항에 대해 통제되고 저장소를 인식하는 보안 평가를 수행합니다.
이는 두 가지 독립적인 분류 작업을 지원합니다: 직접적인 binary 예측(SECURITY_RELEVANT 또는 NON_SECURITY)과 상세한 multiclass 맥락적 분류 체계(세 가지 레이블 — 세 가지 레이블 참조). 각 작업은 zero-shot 또는 agentic 모드로 실행할 수 있습니다.
다음만 필요합니다:
artifact_id별로 하나의 연구 산출물 폴더를 포함하는 디렉터리.artifact_id를 키로 하는 논문 PDF/텍스트 모음.레이블이 지정된 평가 데이터에 대해 학습하거나 튜닝하지 않습니다. 레이블이 지정된 데이터는 추론 후 예측을 평가하는 데만 사용되며 분류기가 이를 볼 수 없습니다. SAFE는 산출물 코드를 실행하지 않으며, 저장소 텍스트는 신뢰할 수 없는 증거로 취급되며 지침이 아닙니다.
이 릴리스에는 완전한 safe_audit 소스, CLI 및 테스트와 함께 외부 데이터 없이 종단 간 실행할 수 있는 세 개의 완전히 합성된 예제 산출물로 구성된 자체 포함 demo/이 포함되어 있습니다. 논문에 사용된 실제 연구 산출물 코퍼스, ground-truth 레이블 및 평가 발견 사항은 제외됩니다.
빠른 시작: 설치 후 데모를 실행하세요 — 데이터 설정 없이 즉시 작동합니다. 구성에서 다루는 config.example.yaml은 자체 발견 사항/산출물을 위한 템플릿이며 편집하기 전에는 실행되지 않습니다.
cd path/to/safe-artifact-auditor
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
API 키 설정:
export OPENAI_API_KEY="your-key"
조직 LiteLLM 프록시의 경우 config.litellm.example.yaml을 대신 사용하세요 — 인라인 주석이 포함되어 있습니다. 자격 증명 및 사용자 정의 헤더 값은 환경 변수에서 읽히며 SAFE 구성 또는 결과 파일에 저장되지 않습니다.
demo/에는 세 개의 작고 완전히 합성된 예제 산출물이 포함되어 있습니다 — 실제 게시된 연구 산출물에서 파생되거나 대응하지 않음 — 분류 체계 레이블당 하나씩이며, 검토자가 외부 데이터 없이 전체 파이프라인을 실행할 수 있습니다:
demo-contextual-risk/ — 호출자가 제공한 URL에서 torch.load로 다운로드한 체크포인트를 역직렬화하는 장난감 연합 학습 체크포인트 집계기입니다. 신뢰할 수 없는 네트워크 소스 입력이 안전하지 않은 역직렬화 싱크에 도달하며, SAFE가 이를 CONTEXTUAL_RISK로 분류할 것으로 예상됩니다.demo-hardening-recommendation/ — 모두 하드코딩된 Python 리터럴인 명령줄에 대해 subprocess.run(..., shell=True)을 실행하는 장난감 벤치마크 하네스로, 호출자가 제어하는 입력이 없습니다. SAFE가 이를 HARDENING_RECOMMENDATION으로 분류할 것으로 예상됩니다: 셸 패턴은 실제이며 플래그를 지정할 가치가 있지만, 외부에서 도달하거나 영향을 줄 수 없습니다.demo-false-positive/ — 가상의 압축 폭탄 권고가 있는 이전 Pillow 버전에 고정된 테스트 픽스처 생성기입니다. 코드는 새 인메모리 이미지만 생성하고 외부 데이터를 열지 않으므로 권고의 실제 코드 경로에 도달하지 않습니다. SAFE가 이를 FALSE_POSITIVE로 분류할 것으로 예상됩니다.demo/findings.csv는 산출물당 하나의 발견 사항을 보유하며, demo/demo-zero-shot.yaml / demo/demo-agentic.yaml은 즉시 실행 가능한 구성입니다(artifact_root: .는 구성 파일 기준으로 해석되므로 demo/ 내부에서 실행):
cd demo
safe-audit run --config demo-zero-shot.yaml
safe-audit run --config demo-agentic.yaml
결과는 각각 demo/runs/demo-zero-shot/ 및 demo/runs/demo-agentic/에 저장됩니다(출력 참조).
CONTEXTUAL_RISKHARDENING_RECOMMENDATIONFALSE_POSITIVE추가 범주나 결정적 레이블 변경 규칙은 사용되지 않습니다. 산출물 자체 코드의 문서화된 격리된 연구/보안 메커니즘은 HARDENING_RECOMMENDATION으로 분류됩니다. 격리가 현실적인 악용 가능성을 제한하더라도 기본 관행이 여전히 실제이기 때문입니다.
SECURITY_RELEVANT: 격리된 의도적 보안 연구 동작을 포함한 유효한 맥락적 위험 또는 강화 우려 사항.NON_SECURITY: 거짓, 불일치, 적용 불가, 부재 또는 명백히 사용되지 않는 영향받는 기능 발견 사항.평가자는 또한 다중 클래스 예측에서 이진 관점을 파생합니다: FALSE_POSITIVE는 NON_SECURITY가 되고, 다른 모든 다중 클래스 레이블은 SECURITY_RELEVANT가 됩니다. 직접 및 파생 이진 결과는 명시적으로 분리되어 유지됩니다.
project/
├── config.yaml
├── data/
│ └── findings.csv
└── artifacts/
├── artifact_001/
├── artifact_002/
└── artifact_003/
매핑은 정확합니다: artifact_id = artifact_001은 artifacts/artifact_001/로 해석됩니다.
필수 CSV 열:
artifact_id;tool;finding_id
선택 열:
artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable
초기 이름 없는 인덱스 열은 무시됩니다. 추가 열은 입력 모델에 의해 보존됩니다.
예:
artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable
artifact_001;semgrep;python.lang.security.audit.subprocess-shell-true;code;HIGH;src/probe.py;42;Shell command uses shell=True;;;;CWE-78;;yes
artifact_002;trivy;DEMO-CVE-0001;dependency;HIGH;;;Affected package (illustrative, not a real CVE);example-lib;1.2.0;CWE-502;8.1;yes
scripts/run_scanners.py 및 scripts/build_findings_csv.py는 Semgrep 및 Trivy를 사용하여 자체 코드에서 위에서 설명한 findings.csv 및 산출물 레이아웃을 직접 생성합니다.
Semgrep 설치(모든 OS에서 동일하게 작동, Linux 포함):
pip install semgrep
Linux에 Trivy 설치 — apt 저장소(Debian/Ubuntu):
sudo apt-get install wget gnupg
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt-get update
sudo apt-get install trivy
또는 공식 설치 스크립트를 사용합니다. 이 스크립트는 모든 Linux 배포판에서 작동하며 바이너리 릴리스를 /usr/local/bin에 설치합니다(해당 디렉터리에 대한 sudo 외에 루트 패키지가 필요 없음):
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sudo sh -s -- -b /usr/local/bin
계속하기 전에 둘 다 PATH에 있는지 확인:
semgrep --version
trivy --version
그런 다음 artifact_root/ 아래에 산출물당 하나의 디렉터리를 배치하고 실행:
python scripts/run_scanners.py artifact_root --output scan-output
python scripts/build_findings_csv.py scan-output --output data/findings.csv
첫 번째 명령은 각 산출물 디렉터리에 대해 Semgrep 및 Trivy(취약점 및 비밀 스캔)를 실행하고 원시 스캐너 JSON을 저장합니다. 두 번째 명령은 해당 JSON을 SAFE 호환 findings.csv로 구문 분석합니다(열은 입력 구조와 일치하며, file은 각 산출물 디렉터리 기준으로 보고됨). 두 스크립트에 --skip-semgrep/--skip-trivy를 전달하여 하나의 도구만 실행할 수 있습니다. run_scanners.py의 --config는 기본 auto 대신 특정 Semgrep 규칙 세트를 고정하며, 이는 편리하지만 재현 가능하게 고정되지는 않습니다.
이 섹션은 자체 발견 사항 CSV 및 산출물 폴더에 대해 SAFE를 실행하기 위한 것입니다(위의 입력 구조 참조). SAFE 실행을 확인하려면 대신 데모를 사용하세요 — 아래 config.example.yaml은 템플릿이며 그대로는 실행되지 않습니다.
cp config.example.yaml config.yaml
그런 다음 실행 전에 input_csv 및 artifact_root(선택적으로 paper_root)를 자체 데이터를 가리키도록 편집하세요.
주요 설정:
model / provider: 정확한 OpenAI 모델 식별자(또는 LiteLLM 별칭) 및 프록시 URL과 자격 증명 환경 변수 이름이 있는 openai 또는 litellm.analysis_mode: zero_shot 또는 agentic.classification_task: binary 또는 multiclass; analysis_mode와 독립적.max_agent_steps: agentic 구성에서만 필요.max_workers / max_output_tokens / max_schema_retries: 동시성, 응답당 출력 상한 및 스키마 무효 응답에 대한 모델 호출 재시도 예산.기본 모델은 gpt-5.6-sol입니다. 가용성, 비용 또는 대기 시간 요구 사항이 다른 경우 명시적으로 변경하세요.
safe-audit run --config config.yaml
또는 콘솔 명령을 설치하지 않고:
PYTHONPATH=src python -m safe_audit.cli run --config config.yaml
포함된 합성 데이터에 대한 실행 가능한 일치 비교는 데모(demo/demo-zero-shot.yaml 및 demo/demo-agentic.yaml)를 참조하세요. 이들은 analysis_mode 및 run_name에서만 다릅니다. Zero-shot은 기본 증거에 대해 한 번의 모델 호출을 수행합니다. Agentic 모드는 동일한 증거에서 시작하며 동일한 구조화된 결과를 반환하기 전에 제한된 읽기 전용 저장소 도구를 호출할 수 있습니다.
runs/<run_name>/
├── config.resolved.yaml
├── run_metadata.json
├── summary.json
├── results.jsonl
├── results.csv
├── profiles/
├── evidence/
├── raw/<finding_uid>/
│ ├── 0001-request.json
│ ├── 0001-response.json (or 0001-error.json)
│ └── final-output.txt
└── logs/
├── events.jsonl
├── result_attempts.jsonl
└── run_sessions.jsonl
results.csv는 분석용입니다. results.jsonl은 완전한 구조화된 레코드를 보존합니다. Evidence 및 원시 모델 출력은 감사 및 오류 분석을 지원합니다. 둘 다 표준입니다: 각 발견 사항의 최신 레코드만 포함하는 반면, logs/result_attempts.jsonl은 추가 전용이며 모든 과거 결과를 보존합니다.
재개 시 SAFE는 먼저 현재의 엄격한 파서로 각 실패한 발견 사항의 저장된 원시 응답을 다시 구문 분석합니다. 고유하게 유효한 분류는 API 호출 없이 복구됩니다. 복구할 수 없는 실패만 모델 추론으로 예약됩니다. 부분적으로 완료된 실행의 실패 전용 연속의 경우 동일한 output_root 및 run_name을 유지하고 다음을 설정하세요:
resume: true
resume_policy: failed_only
레이블이 지정된 골드 CSV(security_label 또는 security_class 열 포함)에 대해 예측을 평가하려면:
safe-audit evaluate --results runs/<run_name>/results.jsonl --gold GOLD.csv --output runs/<run_name>/evaluation.json
PYTHONPATH=src python -m unittest discover -s tests -v
테스트 스위트는 가짜 공급자를 사용하므로 API 키가 필요하지 않습니다.
resume / resume_policy: incomplete는 실패, 누락된 산출물 및 시도되지 않은 발견 사항을 재시도합니다. failed_only는 기록된 성공을 유지하면서 실패만 재시도합니다.cost: 선택적 실시간 비용 계산 및 max_run_cost_usd 종료.