42crunch/api-security-audit-actionCI/CD에서 OpenAPI 계약에 대한 정적 API 보안 감사를 자동화하며, 인증·권한 부여·데이터 제약 조건에 대해 300개 이상의 검사를 실행하고, 최소 점수 게이트와 SARIF 출력을 제공합니다.
REST API 정적 보안 테스트 작업은 OpenAPI Specification(OAS, 이전 명칭: Swagger)을 따르는 REST API 계약을 찾아 철저한 보안 검사를 실행합니다. OAS v2 및 v3.0.x를 모두 지원하며 JSON 및 YAML 형식을 모두 지원합니다.
이 액션은 다음과 같은 시나리오에서 사용할 수 있습니다.
이 액션은 42Crunch API 보안 감사를 기반으로 합니다. 보안 감사는 API 정의에 대한 정적 분석을 수행하며, 인증, 권한 부여 및 데이터 제약과 관련된 모범 사례와 잠재적 취약점에 대한 300개 이상의 검사를 포함합니다.
기본적으로 이 액션은 다음을 수행합니다.
.json 및 .yaml 파일을 찾습니다.이렇게 하면 리포지토리에서 새로 추가되거나 변경된 API 계약을 찾을 수 있습니다.
API 검색에 포함하거나 제외할 리포지토리의 특정 부분이나 파일 이름 마스크를 지정하여 액션 동작을 세밀하게 조정할 수 있습니다. 검색을 완전히 비활성화하고 대신 검사할 특정 API 파일만 나열하여 42Crunch API 보안 플랫폼의 기존 API에 매핑할 수도 있습니다. 이러한 모든 설정은 구성 파일 42c-conf.yaml에서 구성합니다. 고급 예제는 여기를 참조하세요.
검색된 모든 API는 42Crunch 플랫폼의 API 컬렉션에 업로드됩니다. 기본적으로 액션은 환경 변수 GITHUB_REPOSITORY 및 GITHUB_REF를 사용하여 API 컬렉션이 시작된 리포지토리와 브랜치/태그/PR 이름을 지정합니다. default-collection-name 액션 매개변수를 사용하여 이름을 재정의할 수 있습니다. 이후 실행 중에 컬렉션의 API는 리포지토리의 변경 사항과 동기화된 상태로 유지됩니다.
이 액션을 GitHub의 CI/CD 워크플로에 추가하여 보안 문제가 있는 API 정의에서 실패하도록 하세요.
보안 감사는 각 API 계약에 API의 보안 표면을 반영하는 0~100점의 감사 점수를 부여합니다. GitHub Action의 min-score 매개변수를 사용하여 액션이 실패하는 감사 점수의 임계값을 설정할 수 있습니다(다른 값이 지정되지 않은 경우 기본값은 75). 이렇게 하면 품질이 낮은 API 정의를 조기에 발견하고 설계 단계에서 문제를 해결하는 데 도움이 됩니다.
더 고급 실패 조건은 구성 파일 42c-conf.yaml에서 설정할 수 있습니다. 예를 들어 카테고리(보안 또는 데이터 검증)별 감사 점수, 문제의 심각도 수준, 또는 문제 ID로 지정된 특정 문제를 설정할 수 있습니다. 고급 예제는 여기를 참조하세요.
또한 이 플러그인은 플랫폼 수준에서 정의된 보안 품질 게이트(기본 또는 태그 기반)를 적용합니다. 보안 품질 게이트는 기업 내에서 정의된 애플리케이션 보안 요구 사항을 적용합니다.
액션이 실행될 때마다 각 OpenAPI 파일에 대한 상세하고 우선순위가 지정된 실행 가능한 보고서 링크가 포함됩니다:
링크를 따라 42Crunch 플랫폼에서 상세 보고서를 읽으세요:
42Crunch 감사에서 발견한 문제를 GitHub의 코드 스캐닝 알림 아래 보안 탭에서 직접 추적할 수도 있습니다.
이 기능을 사용하려면 GitHub 워크플로의 액션 매개변수에 upload-to-code-scanning:true를 포함하기만 하면 됩니다.
알림을 클릭하면 코드에서 정확한 위치를 확인하고 취약점 세부 정보와 권장 수정 단계를 확인할 수 있습니다.
이 액션은 42Crunch API 보안 감사 서비스를 사용합니다. 액션을 사용하기 전에 42Crunch 플랫폼에 계정이 있어야 합니다. 42Crunch 고객이 아닌 경우 이 페이지에서 무료 계정을 요청할 수 있습니다: https://42crunch.com/get-started/.
그런 다음 문서에 설명된 단계에 따라 액션이 42Crunch 플랫폼에 인증하는 데 사용할 API 토큰을 만들고 GitHub에 시크릿으로 저장하세요.
api-token필수 GitHub 액션이 42Crunch 플랫폼에 인증하는 데 사용하는 API 토큰입니다. API 토큰을 워크플로 파일에 직접 넣지 마세요! 대신 리포지토리 설정에서 GitHub 시크릿을 만들고 아래 예제와 같이 참조하세요.
min-scoreOpenAPI 파일이 도달해야 하는 최소 감사 점수입니다. 그렇지 않으면 액션이 실패합니다. 기본값은 75입니다.
upload-to-code-scanning감사 결과를 GitHub 코드 스캐닝에 업로드합니다. 기본값은 false입니다. 이 단계가 성공하려면 워크플로에 특정 권한이 있어야 합니다.
...
jobs:
run_42c_audit:
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
...
ignore-failurestrue로 설정하면 설정한 실패 조건(예: min-score 또는 SQG 기준)이 충족되더라도 실행이 성공적으로 완료되도록 강제합니다. 기본값은 false입니다.
이 매개변수는 SQG 실패 시나리오를 강제하지 않고 감지하려는 경우(즉, 빌드를 중단하기 전에 개발 팀에 유예 기간을 제공) 유용할 수 있습니다.
ignore-network-errorstrue로 설정하면 42Crunch 플랫폼에 연결 실패 등의 네트워크 오류가 발생해도 실행이 성공적으로 완료되도록 강제합니다. 기본값은 false입니다.
skip-local-checkstrue로 설정하면 42c-conf.yaml 파일에 설정된 모든 실패 조건(예: 최소 점수)을 비활성화하고 SQG에 정의된 기준이 충족되지 않은 경우에만 실행을 실패시킵니다. 기본값은 false입니다.
platform-url42Crunch 플랫폼에 액세스하는 URL입니다. 기본값은 https://us.42crunch.cloud입니다.
엔터프라이즈 고객인 경우 프로덕션 플랫폼에 액세스하는 데 사용하는 URL을 입력하세요.
root-directory42c-conf.yaml 구성 파일이 포함된 루트 디렉터리입니다. 지정하지 않으면 플러그인의 현재 작업 디렉터리가 대신 사용되며, 일반적으로 체크아웃된 리포지토리의 루트에 해당합니다.
default-collection-name검색된 API에 대한 컬렉션을 만들 때 사용되는 기본 컬렉션 이름입니다. 이름이 지정되지 않으면 리포지토리 및 브랜치/PR 정보에서 기본 이름이 생성됩니다.
log-level로그의 세부 수준입니다. FATAL, ERROR, WARN, INFO, DEBUG 중 하나입니다. 기본값은 INFO입니다.
share-everyoneCI/CD 작업이 만든 API 컬렉션을 42Crunch 플랫폼의 조직 내 모든 사용자와 자동으로 공유합니다. 허용되는 값은 OFF, READ_ONLY, READ_WRITE입니다. 기본값은 OFF입니다. 액션이 실행되는 ID(API 토큰 소유자)에게 Share with Everyone 권한이 있어야 합니다. 그렇지 않으면 작업이 403 오류와 함께 실패합니다.
json-report감사 실행 보고서를 JSON 형식으로 지정된 파일에 씁니다. 실행 보고서는 생성, 업데이트 및 삭제된 API 목록을 자세히 설명합니다. 이는 후속 파이프라인 단계에서 감사 실행 결과를 자동으로 사용하려는 경우 유용합니다. 기본적으로 보고서는 작성되지 않습니다.
api-tagsCI/CD 작업은 새로 생성된 API에 태그를 자동으로 할당할 수 있습니다. 태그는 category1:name1 category2:name2 형식으로 지정합니다. 이 플래그는 선택 사항입니다.
sarif-report감사 원시 JSON 형식을 SARIF로 변환하고 결과를 지정된 파일에 저장합니다. 기본적으로 보고서는 작성되지 않습니다.
audit-timeout감사 보고서의 최대 시간 제한(초)을 설정합니다. 결과가 해당 간격 내에 준비되지 않으면 작업이 실패합니다. 기본값: 600
42Crunch 플랫폼에서 API 토큰을 만들고 해당 값을 API_TOKEN이라는 리포지토리 시크릿에 복사하세요.
기존 워크플로에 추가하는 일반적인 새 단계는 다음과 같습니다:
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
리포지토리의 콘텐츠를 확인하고, 프로젝트에서 찾은 각 OpenAPI 파일에 대해 보안 감사를 실행하고, 실행 파일을 아티팩트로 저장하는 일반적인 워크플로는 다음과 같습니다:
name: "42crunch-audit-workflow"
# follow standard Code Scanning triggers
on:
push:
branches: [ "main" ]
pull_request:
# The branches below must be a subset of the branches above
branches: [ "main" ]
schedule:
- cron: '19 9 * * 6'
env:
PLATFORM_URL: https://us.42crunch.cloud
jobs:
run_42c_audit:
environment: QA
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
runs-on: ubuntu-latest
steps:
- name: checkout repo
uses: actions/checkout@v3
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
platform-url: ${{ env.PLATFORM_URL}}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
# Upload results to Github code scanning
upload-to-code-scanning: false
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
- name: save-audit-report
if: always()
uses: actions/upload-artifact@v3
with:
name: auditaction-report-${{ github.run_id }}
path: audit-action-report-${{ github.run_id }}.json
if-no-files-found: error
이 액션은 42Crunch Ecosystems 팀이 유지 관리합니다. 문제가 발생하거나 여기에서 답변되지 않은 질문이 있는 경우 support.42crunch.com에서 지원 티켓을 생성할 수 있습니다.
문제를 보고할 때 다음을 포함하세요: