DepAlert Agent

CTWall

이 도구는 CTWall 플랫폼의 일부입니다. 참조: CTWall

설명

DepAlert는 CI/CD 파이프라인을 위한 오픈소스 보안 게이트입니다. SBOM을 악성코드 인텔리전스 데이터와 분석하여 빌드에 알려진 악성 패키지가 포함되어 있는지 신속하게 알려줍니다.

DepAlert는 릴리스 속도, 위험 및 비용에 직접적인 영향을 미치는 핵심 소프트웨어 공급망 문제를 해결합니다:

• SBOM 분석을 자동 CI/CD 릴리스 게이트로 전환하여 악성코드가 프로덕션에 도달하는 것을 방지합니다.
• 모든 파이프라인 실행에서 팀에 빠르고 결정적인 평결(MALWARE, CLEAN, UNKNOWN)을 제공하여 보안 병목 현상을 줄입니다.
• 일관된 정책 모델(fail-on)과 감사 가능한 예외 워크플로로 팀 전체의 위험 결정을 표준화합니다.
• 배포 후가 아닌 배포 전에 프로젝트 범위의 검사를 적용하여 인시던트 및 규정 준수 노출을 낮춥니다.
• 수동 보안 인계를 모든 파이프라인에서 재사용할 수 있는 하나의 CLI 단계로 대체하여 개발자 생산성을 향상시킵니다.

빠른 시작

단계별 지침은 00_quick_start.md를 참조하세요.

도구 목적

depalert는 다음을 수행하는 CI/CD CLI입니다:

1. SBOM을 CTWall에 업로드합니다 (POST /api/v1/ingest)
2. 리비전 평결을 동기적으로 대기합니다 (GET /api/v1/tests/{testId}/revisions/{revisionId}/depalert-verdict)
3. 파이프라인 친화적인 결과와 종료 코드를 반환합니다

이 도구는 프로젝트 범위로 적용됩니다. 다음 방법으로 대상 프로젝트를 선택할 수 있습니다:

• project-id (UUID), 또는
• project-name (API를 통해 확인됨).

둘 다 제공된 경우 project-id가 우선합니다.

DepAlert 결과

DepAlert는 하나의 리비전 결과를 반환합니다:

• CLEAN - 악성코드 발견 없음 - 종료 코드 0
• MALWARE - 리비전에서 하나 이상의 악성코드 발견됨 - 종료 코드 1
• UNKNOWN - 아직 분석이 완료되지 않음 - 종료 코드 2 (또는 fail-on=NONE인 경우 종료 코드 0)

CLI 출력 형식:

VERDICT: <MALWARE|CLEAN|UNKNOWN> (malware=<n> clean=<n> unknown=<n> total=<n>, elapsed=<t>)

JSON 모드는 --format json(또는 CTWALL_OUTPUT=json)을 통해 사용할 수 있습니다.

JSON 출력 예시:

{
  "version": "1.1.0",
  "status": "success",
  "exitCode": 0,
  "projectId": "28e241e3-b924-4e1a-abc2-d592e8dd811c",
  "testId": "13271a70-cf47-4f3b-9e33-cb41ed0c793e",
  "revisionId": "c4d1f1a4-c018-488e-9dd0-6cfdbed83bf3",
  "verdict": "CLEAN",
  "malwareComponents": 0,
  "cleanComponents": 12,
  "unknownComponents": 0,
  "totalComponents": 12,
  "elapsedMs": 1842,
  "timedOut": false,
  "failOn": "MALWARE",
  "message": "depalert completed"
}

예상 결과

VERDICT: <MALWARE|CLEAN|UNKNOWN> (malware=<n> clean=<n> unknown=<n> total=<n>, elapsed=<t>)

• 종료 코드 0 = 통과
• 종료 코드 1 = 정책 실패 또는 런타임 오류
• 종료 코드 2 = 최종 평결이 UNKNOWN이고 fail-on이 NONE이 아님

CLI 및 환경 구성

프로젝트 대상 지정 규칙

• project-id 또는 project-name 중 하나 이상이 필요합니다.
• project-name은 GET /api/v1/projects를 사용하여 확인됩니다.
• 이름 일치는 대소문자를 구분하지 않는 정확한 일치입니다.
• 동일한 이름과 일치하는 활성 프로젝트가 두 개 이상 있으면 모호성 오류로 실행이 실패합니다.
• 필수 값은 플래그 또는 환경 변수로 제공할 수 있습니다. 플래그가 우선합니다.

연결

• 로컬이 아닌 호스트에는 https가 필요합니다.
• 테스트/비프로덕션 환경에서는 다음을 사용할 수 있습니다:
  • --allow-insecure, 또는
  • CTWALL_ALLOW_INSECURE=true.
• 자체 서명된 HTTPS 인증서(테스트/비프로덕션 전용)의 경우 다음을 사용할 수 있습니다:
  • --skip-tls-verify, 또는
  • CTWALL_SKIP_TLS_VERIFY=true.

보안

를 참조하세요.

라이선스

DepAlert는 BSD 3-Clause 라이선스에 따라 사용이 허가됩니다.