guardia-ai/gitlab-componentGitLab CI/CD 파이프라인을 위한 EU AI 법 준수 스캐너 — AI/ML 라이브러리를 탐지하고 MR 댓글로 위험 분류를 게시합니다.
GitLab을 쉽게 시작할 수 있도록 다음과 같은 권장 단계를 안내해 드립니다.
이미 전문가이신가요? 이 README.md를 편집하여 자신만의 것으로 만드세요. 더 쉽게 만들고 싶으신가요? 하단의 템플릿을 사용하세요!
cd existing_repo
git remote add origin https://gitlab.com/guardia-ai/gitlab-component.git
git branch -M main
git push -uf origin main
GitLab에 내장된 지속적 통합(CI)을 사용하세요.
이 README를 나만의 것으로 만들 준비가 되셨다면, 이 파일을 편집하고 아래의 유용한 템플릿을 사용하세요 (또는 원하는 방식으로 자유롭게 구성해도 됩니다 - 이것은 단지 시작점일 뿐입니다!). 이 템플릿을 제공해 주신 makeareadme.com에 감사드립니다.
모든 프로젝트는 다르므로, 다음 섹션 중 어떤 것이 귀하의 프로젝트에 적합할지 고려해 보세요. 템플릿에 사용된 섹션은 대부분의 오픈 소스 프로젝트에 대한 제안 사항입니다. README가 너무 길고 상세할 수도 있지만, 너무 짧은 것보다는 긴 것이 낫다는 점을 명심하세요. README가 너무 길다고 생각되면, 정보를 잘라내기보다는 다른 형태의 문서를 활용하는 것을 고려하세요.
프로젝트에 대해 설명이 되는 이름을 선택하세요.
사람들이 귀하의 프로젝트가 무엇을 할 수 있는지 구체적으로 알 수 있게 해주세요. 맥락을 제공하고 방문자가 익숙하지 않을 수 있는 참조 자료에 대한 링크를 추가하세요. 기능 목록이나 배경(Background) 하위 섹션도 여기에 추가할 수 있습니다. 프로젝트에 대안이 있다면, 차별화 요소를 여기에 나열하는 것이 좋습니다.
일부 README에서는 프로젝트의 모든 테스트 통과 여부와 같은 메타데이터를 전달하는 작은 이미지를 볼 수 있습니다. Shields를 사용하여 README에 배지를 추가할 수 있습니다. 많은 서비스에서 배지 추가 방법에 대한 지침도 제공합니다.
무엇을 만드느냐에 따라 스크린샷이나 동영상을 포함하는 것이 좋은 생각일 수 있습니다 (실제 동영상보다는 GIF를 자주 볼 수 있습니다). ttygif 같은 도구가 도움이 될 수 있지만, 더 정교한 방법을 원한다면 Asciinema를 확인해 보세요.
특정 생태계 내에서는 Yarn, NuGet, Homebrew 등을 사용하는 일반적인 설치 방법이 있을 수 있습니다. 그러나 README를 읽는 사람이 초보자일 가능성을 고려하여 더 많은 지침을 제공하는 것이 좋습니다. 구체적인 단계를 나열하면 모호함을 없애고 사람들이 최대한 빨리 프로젝트를 사용할 수 있도록 도와줍니다. 특정 프로그래밍 언어 버전, 운영 체제와 같은 특정 컨텍스트에서만 실행되거나 수동으로 설치해야 하는 종속성이 있는 경우 요구 사항(Requirements) 하위 섹션도 추가하세요.
예제를 자유롭게 사용하고, 가능하다면 예상 출력을 보여주세요. 데모할 수 있는 가장 작은 예제를 인라인으로 포함하고, 너무 길어서 README에 포함하기 어려운 경우 더 정교한 예제에 대한 링크를 제공하는 것이 도움이 됩니다.
사용자가 도움을 받을 수 있는 곳을 알려주세요. 이슈 트래커, 채팅방, 이메일 주소 등의 조합이 될 수 있습니다.
향후 릴리스에 대한 아이디어가 있다면 README에 나열하는 것이 좋습니다.
기여를 받고 있는지, 그리고 기여를 수락하기 위한 요구 사항은 무엇인지 명시하세요.
프로젝트에 변경 사항을 적용하려는 사람들을 위해 시작 방법에 대한 문서를 제공하는 것이 좋습니다. 실행해야 할 스크립트나 설정해야 할 환경 변수가 있을 수 있습니다. 이러한 단계를 명확히 하세요. 이 지침은 미래의 자신에게도 유용할 수 있습니다.
코드 린트 또는 테스트 실행 명령도 문서화할 수 있습니다. 이러한 단계는 높은 코드 품질을 보장하고 변경 사항이 실수로 무언가를 망가뜨릴 가능성을 줄이는 데 도움이 됩니다. 특히 브라우저 테스트를 위한 Selenium 서버 시작과 같은 외부 설정이 필요한 경우 테스트 실행 지침을 제공하는 것이 매우 유용합니다.
프로젝트에 기여한 사람들에게 감사를 표하세요.
오픈 소스 프로젝트의 경우 어떻게 라이선스가 부여되었는지 명시하세요.
프로젝트에 더 이상 에너지나 시간을 쏟을 수 없다면, README 상단에 개발이 느려졌거나 완전히 중단되었다는 메모를 추가하세요. 누군가가 프로젝트를 포크하거나 관리자/소유자로 자원하여 프로젝트를 계속 이어갈 수도 있습니다. 또한 유지관리자를 명시적으로 요청할 수도 있습니다.
스캐너는 사용 중인 어떤 AI 라이브러리인지 탐지하는 것 이상으로, 소스 코드를 읽고 특정 라인에서의 구체적인 의무 사항을 보고합니다.
| 규칙(Rule) | 내용(What it looks for) |
|---|---|
GA-ART50-001 | 모델에 도달하는 사용자 대상 엔드포인트가 있으며, 응답이 AI로 생성되었음을 저장소 어디에도 공개하지 않은 경우 |
GA-ART12-001 | 로깅, 감사 또는 추적 호출이 범위 내에 없는 상태로 모델이 호출된 경우 |
발견 사항은 세 가지 방식으로 나타납니다: 병합 요청에 코멘트로, 코드 품질 보고서를 통해 병합 요청 diff에 마커로, 그리고 API 키가 있으면 Guardia 대시보드에 기록으로 — 커밋별로 무엇을 수정했고 무엇을 새로 도입했는지 추적합니다.
include:
- component: gitlab.com/guardia-ai/gitlab-component/scan@main
inputs:
guardia_api_key: $GUARDIA_API_KEY # 선택 사항 — 기록 유지
code_analysis: 'true'
fail_on_findings: 'none'
발견 사항은 스스로 해결됩니다. 코드를 수정하면(당사의 패치든 귀하의 패치든) 다음 스캔에서 더 이상 보고되지 않습니다. 클릭할 것이 없습니다.
대신 수락하려면 코드에 다음과 같이 명시하세요:
# guardia: ignore GA-ART50-001 — notice is rendered by the chat UI shell
이렇게 하면 빌드가 실패하지 않으며, git blame에서 작성자가 포함된 문서화된 위험 수용으로 대시보드에 도착합니다. 이는 감사자가 보고 싶어하는 내용입니다.
5년 된 저장소에는 현재 팀 구성원이 발생시키지 않은 발견 사항이 있을 것입니다. 한 번 동결시키고, 새로운 작업만 깔끔하게 유지하면 됩니다:
guardia-scan . --write-baseline .guardia/baseline.json
해당 파일을 커밋하세요. 베이스라인에 포함된 발견 사항은 보고서와 대시보드에 계속 표시되지만 검사에 실패하지 않습니다. 이후에 도입된 모든 것은 실패하게 됩니다.
각 실행은 변조 방지 기록을 작성할 수 있습니다 — 무엇이 발견되었는지, 어떤 커밋에서, 어떤 규칙 팩 버전에서, 그리고 각 규칙이 당시 얼마나 많은 법적 검토를 받았는지:
- uses: GharbiiAhmed/guardia-ai-action@v1
with:
evidence-file: guardia-evidence.json
evidence-signing-key: ${{ secrets.GUARDIA_EVIDENCE_KEY }} # 선택 사항
기록은 해시로 연결되므로, 과거 기록 하나를 변경하면 그 이후의 모든 기록이 깨집니다. 서명 키가 없으면 내부 일관성(authenticity가 아닌)만 증명합니다 — 기록 자체가 그렇게 명시하여 사용자가 추측하지 않도록 합니다.
발견 사항은 코드가 무엇을 하는지와 의무 사항을 인용합니다. 귀하가 위반했다고 주장하지 않습니다. 의무 사항의 적용 여부는 시스템의 목적과 배포 컨텍스트에 따라 달라지며, 코드 스캔으로는 결정할 수 없습니다. 규칙은 Regulation (EU) 2024/1689를 그대로 인용하므로 귀하가 직접 추론을 확인할 수 있습니다.
탐지는 완전히 오프라인으로 실행됩니다. 귀하의 소스는 실행 환경을 벗어나지 않습니다.