주요 콘텐츠로 건너뛰기
AI 튜토리얼

Iron Laws로 AI 생성 코드 감사 및 개선

Iron Laws 설치, 프로젝트 스캔, AI용 수정 지침 생성, 적용 기준 구성, 기준선 및 억제 관리, AI 패치 검증, SARIF 보고서와 GitHub Actions 통합 방법을 알아보세요.

약 17분 소요
Iron Laws로 AI 생성 코드 감사 및 개선
Iron Laws 프로젝트 로고

Iron Laws란?

Iron Laws는 오철칙이라고도 하며, AI로 생성된 프로젝트에서 흔히 발생하는 보안 및 유지 관리 문제를 찾아내도록 설계된 정적 검사 도구입니다. 이 도구는 기업 및 공공 부문 시스템 통합 감사에서 얻은 교훈을 적용하고, 각 발견 항목을 이해하기 쉬운 언어로 설명합니다.

이 도구는 애플리케이션이 단순히 실행되는지만 확인하지 않습니다. 하드코딩된 비밀 값, 안전하지 않은 입력 처리, 삼켜진 예외, 인증되지 않은 관리자 API, 누락된 Supabase 또는 Firebase 접근 제어, 커밋된 .env 파일, 중복 함수, 순환 종속성, 타입 안전성 우회와 같은 문제를 검사합니다.

Iron Laws는 AI 코딩 도우미에 붙여 넣을 수 있는 구조화된 수정 지침도 생성합니다. 이를 통해 다음과 같은 반복 가능한 작업 흐름을 만들 수 있습니다.

AI로 빌드 → iron-laws check → iron-laws fix-prompt
→ AI에 발견 항목 수정 요청 → 다시 검사 실행

Iron Laws는 개발 중 검토를 돕는 도구이며, 공식 인증 제품이나 애플리케이션의 보안을 입증하는 수단이 아닙니다. 테스트, 코드 리뷰 및 기타 보안 도구와 함께 사용하세요.

주요 기능

보안 및 품질 검사

이 프로젝트에는 여러 영역을 아우르는 90개의 규칙이 포함되어 있습니다.

  • 참조 규칙: 대한민국 행정안전부의 소프트웨어 개발 보안 가이드에서 참조한 구현 단계 항목 49개 전체를 다룹니다. 인젝션, XSS, SSRF, XXE, 취약한 암호화, 인증서 검증 비활성화, 안전하지 않은 역직렬화, 오류 처리 및 메모리 안전성 등이 포함됩니다.
  • AI 코드 교정: 하드코딩된 설정, 비밀 값의 대체값, 프런트엔드 비밀 값 노출, 안전하지 않은 CORS, 누락된 접근 규칙, 위험한 Docker 또는 CI 설정, 의존성 오타, 버전이 고정되지 않은 의존성, 민감 정보 로깅, IDOR 및 쿠키 속성을 검사합니다.
  • 아키텍처 검사: 지나치게 큰 함수와 파일, 부적절한 계층 종속성, 요청 핸들러에서의 직접적인 데이터베이스 접근, 순환 종속성, 중복 함수, 반복되는 문자열 상수 및 누락된 테스트를 검사합니다.
  • 타입 안전성 검사: TypeScript의 any 및 @ts-ignore, Python의 type: ignore 및 캐스팅, Java의 원시 타입, C#의 dynamic, 그리고 지원되는 다른 언어의 타입 시스템 우회를 검사합니다.

이해하기 쉬운 발견 항목 및 수정 지침

모든 발견 항목에는 문제에 대한 설명, 위험한 이유 및 수정 방법이 포함됩니다. 규칙이 공개된 가이드 항목에 해당하는 경우 보고서에 해당 항목 번호와 CWE 매핑이 포함됩니다. 프로젝트별 품질 규칙은 외부 요구 사항이 아닌 Iron Laws 규칙으로 명확히 표시됩니다.

AI용 수정 프롬프트

fix-prompt 명령은 심각도별로 발견 항목을 정리하고 AI 코딩 도구용 지침으로 변환합니다. 또한 이 프롬프트는 오류를 삼키지 않기, 소스 코드에 비밀 값을 넣지 않기, 타입 검사를 우회하지 않기, 중복 구현을 만들지 않기와 같은 원칙을 강조합니다.

로컬 파싱

필요한 파서가 패키지에 포함되어 있으므로 설치 후에는 네트워크 연결 없이 검사를 실행할 수 있습니다.

언어 및 파일 지원

지원 수준은 언어와 파일 형식에 따라 다릅니다.

  • 심층 지원: Python, JavaScript, TypeScript, Java 및 C#은 구문 분석, 입력 추적 및 가장 폭넓은 규칙 적용 범위를 지원합니다.
  • 기본 지원: Go와 PHP는 구문 분석 및 주요 인젝션, 오류 처리, 암호화 검사를 지원합니다.
  • 제한적 지원: Rust와 C/C++는 오류 처리, 메모리 사용, 서식 문자열, API 및 타입 우회 검사를 지원합니다.
  • 구성 및 정의 파일: SQL, YAML, JSON, .env, Dockerfile, Compose, GitHub Actions, MyBatis XML 및 HTML 템플릿에서 관련 비밀 값, 접근 제어, 배포 및 이스케이프 문제를 검사합니다.

함수 내부에서 Iron Laws는 분기, 반복문 및 예외를 통한 흐름을 분석합니다. 동일한 파일의 헬퍼 호출을 최대 4단계까지 추적합니다. Python은 분석 한도 내에서 가져오기를 통한 실험적 파일 간 추적도 지원합니다. 다른 언어의 파일 간 흐름은 누락되거나 검토가 필요한 항목으로 보고될 수 있습니다.

설치

Iron Laws에는 Python 3.12 이상이 필요합니다. uv를 사용해 독립 실행형 도구로 설치하는 방법을 권장합니다.

uv tool install git+https://github.com/JinHo-von-Choi/iron-laws.git

또는 pip으로 설치할 수 있습니다.

pip install git+https://github.com/JinHo-von-Choi/iron-laws.git

설치 후 포함된 규칙을 나열하여 명령을 사용할 수 있는지 확인합니다.

iron-laws rules

언어 및 규칙별 구현과 검증 상태를 확인하려면 다음을 실행합니다.

iron-laws support

파서가 있다는 사실이 해당 언어에 대한 모든 규칙의 검증을 의미하지는 않으므로 이 구분은 중요합니다.

첫 번째 검사 실행

현재 프로젝트 검사

프로젝트 디렉터리에서 터미널을 열고 다음을 실행합니다.

iron-laws check .

기본적으로 이 명령은 HIGH 심각도 이상인 발견 항목을 찾으면 실패합니다. 종료 코드는 다음과 같습니다.

  • 0: 선택한 심각도 정책에 따라 검사를 통과했습니다.
  • 1: 설정된 실패 심각도 이상에 해당하는 발견 항목이 하나 이상 있습니다.
  • 2: 입력 또는 구성이 유효하지 않거나, 검사된 파일이 없거나, 규칙 오류 또는 파일 읽기 실패와 같은 문제로 검사를 완료할 수 없습니다.

불완전한 검사는 확정된 등급이나 통과 결과를 받지 못합니다. 그 이유는 diagnostics에 기록됩니다. 또한 --allow-empty를 명시적으로 제공하지 않는 한, 비어 있는 대상은 성공적인 스캔으로 처리되지 않습니다.

개별 규칙 이해하기

규칙을 일반 언어로 설명해야 할 때는 explain을 사용합니다:

iron-laws explain IL-501

참조된 49개 구현 항목 중 어떤 항목이 적용되는지도 확인할 수 있습니다:

iron-laws coverage

보고서 생성하기

참조된 49개 항목 전체의 검사 상태가 포함된 Markdown 보고서를 생성하려면 다음을 실행합니다:

iron-laws audit . --format markdown -o report.md

GitHub Code Scanning 또는 다른 호환 시스템에서 사용할 SARIF 파일을 생성하려면 다음을 사용합니다:

iron-laws audit . --format sarif -o iron-laws.sarif

AI 코딩 어시스턴트용 지침 생성하기

검사 결과를 검토한 후 AI용 수정 프롬프트를 생성합니다:

iron-laws fix-prompt .

생성된 지침을 코딩 어시스턴트에 붙여 넣고, 제안된 변경 사항을 검토한 다음 검사를 다시 실행합니다:

iron-laws check .

fix-prompt 명령은 결과가 존재하더라도 지침 생성을 목적으로 하므로 종료 코드 0을 반환합니다. 이 명령을 배포 게이트로 사용하지 마세요. 강제 적용에는 check 또는 audit을 사용합니다.

인식된 시크릿 값은 보고서와 생성된 프롬프트에서 ****로 마스킹됩니다. 하지만 인식되지 않은 시크릿은 자동으로 마스킹할 수 없으므로, 생성된 텍스트를 외부 AI 서비스로 보내기 전에 검토하세요.

프로젝트 정책 구성하기

다음 명령으로 초기 구성 파일을 생성합니다:

iron-laws init

이 프로젝트는 .iron-laws.yml을 사용합니다. 일반적인 구성은 다음과 같습니다:

fail_on: HIGH
excludes: [".git", "node_modules", "dist"]
disabled_rules: ["ARC-206"]
limits:
  max_function_lines: 80
  max_file_lines: 600
  max_parameters: 7
  max_nesting: 5
  duplicate_similarity: 0.9

fail_on 설정에는 CRITICAL, HIGH, MEDIUM, LOW을 사용할 수 있습니다. 적용되는 우선순위는 --fail-on 명령줄 옵션, 구성 파일, 기본값인 HIGH 순서입니다. 보고서에는 활성 임계값을 제공한 출처가 기록됩니다.

기본적으로 Iron Laws는 검사 대상 디렉터리의 구성을 사용합니다. 특정 파일을 선택하려면 --config을 사용하고, 상위 디렉터리에서 찾으려면 --search-parents를 사용합니다. 알 수 없는 키와 잘못된 설정은 조용히 무시되지 않으며 종료 코드 2가 반환됩니다.

의도적인 예외 처리하기

오탐 또는 의도적인 예외는 사유가 포함된 억제 지시문이 있을 때만 억제할 수 있습니다. 사유가 없는 주석은 무시됩니다.

Python에서 하나의 결과를 억제하려면 다음과 같이 합니다:

except ImportError:  # iron-laws: ignore[IL-301] Optional dependency disables this feature
    yaml = None

파일 전체에서 규칙을 억제하려면 처음 30줄 안에 ignore-file 지시문을 작성합니다:

# iron-laws: ignore-file[IL-102] Pattern definitions intentionally identify weak algorithms

억제 지시문에는 만료일을 포함할 수 있습니다:

# iron-laws: ignore[IL-101] until=2026-12-31 Temporary exception with documented reason

만료된 억제 지시문은 더 이상 적용되지 않으며 보고서에 표시됩니다. Iron Laws는 사용되지 않은 억제 지시문과 알 수 없는 규칙 ID에 대한 참조도 보고합니다.

기존 프로젝트에 Iron Laws 도입하기

베이스라인 생성하기

기존 저장소에 이미 승인된 결과가 있다면 이를 승인된 기술 부채로 기록합니다:

iron-laws baseline create .

그런 다음 저장된 베이스라인과 비교하여 새로 추가된 결과만 평가합니다:

iron-laws check . --baseline .iron-laws-baseline.json

변경된 파일 검사하기

수정된 파일에 집중한 풀 리퀘스트 피드백을 받으려면 메인 브랜치와 비교합니다:

iron-laws check . --changed-since origin/main

README에서는 저장소 전체의 문제가 누락되지 않도록 변경 파일 검사와 전체 검사 및 정기 검사를 함께 실행할 것을 권장합니다.

검토 피드백 기록하기

검토가 필요한 것으로 표시된 결과는 분류하고 검토 비용을 지정할 수 있습니다:

iron-laws feedback add IL-501 src/a.py:3 --verdict false-positive --minutes 10

AI가 생성한 패치 검증하기

Iron Laws에는 AI가 코드를 수정한 후 무엇을 검증했고 무엇을 검증하지 않았는지에 대한 증거를 보존하는 고급 워크플로가 포함되어 있습니다.

증거 계약 확인하기

증거 계약은 검사가 완료되었는지와 실제로 필요한 증거를 생성했는지를 구분합니다:

iron-laws check . --contract .iron-laws-contract.yml

해결되지 않은 입력 소스는 자동으로 문제가 없는 결과로 변환되지 않습니다. 현재 증거 계약 적용 범위에는 Python 명령 실행, 경로 접근, SQL 구성 제품군이 포함됩니다.

패치 검증 영수증 생성하기

제안된 패치를 검사하고 검증 영수증을 저장하려면 다음과 같은 명령을 실행합니다:

iron-laws verify-patch . --patch fix.diff \
  --finding IL-504@app.py:6 \
  --runner docker \
  --image IMAGE_NAME \
  -o receipt.json

검증기는 동일한 정책을 사용하여 원본과 후보를 비교합니다. 삭제된 테스트, 추가된 건너뛰기, 새로 추가된 무시 주석, 약화된 정책과 같은 의심스러운 변경 사항은 별도로 보고합니다. 경고가 사라졌다는 사실만으로는 유효한 수정이 이루어졌다는 증거로 간주하지 않습니다.

테스트는 자격 증명 없이 폐기 가능한 격리 환경에서만 실행됩니다. 격리를 확보할 수 없는 경우 Iron Laws는 호스트에서 테스트를 묵묵히 실행하지 않고 결과를 미확정 상태로 둡니다.

구별 가능한 회귀 테스트 제안

발견 사항에 대한 후보 회귀 테스트 사양을 생성할 수 있습니다:

iron-laws regression propose . --finding IL-504@app.py -o spec.yml

의도된 검증 패턴은 결함 때문에 원본이 실패하고, 후보가 통과하며, 수정 사항을 되돌린 뮤턴트가 다시 실패하는지 확인합니다. README에서는 이 순서를 세 번 반복하도록 설명합니다. 생성된 테스트는 확인될 때까지 제안 상태로 유지됩니다.

사람의 승인 기록

사유와 함께 승인을 저장합니다:

iron-laws approvals add . \
  --finding IL-504@app.py \
  --reason "Documented review reason" \
  --store approvals.jsonl

스캔 중 유효한 승인을 적용합니다:

iron-laws check . --approvals approvals.jsonl

승인은 해당 가정이 유지되는 동안에만 유효합니다. 호출자, 데이터 흐름, 새니타이저, 접근 범위 또는 규칙의 의미가 변경되면 재검토가 필요할 수 있습니다. 취약한 코드가 복제되었다고 해서 기존 승인을 상속하지는 않습니다.

GitHub Actions와 통합

다음 워크플로는 Iron Laws를 설치하고 SARIF 보고서를 업로드한 다음, 심각도가 높은 배포 게이트를 적용합니다:

name: Iron Laws
on: [push, pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv tool install git+https://github.com/JinHo-von-Choi/iron-laws.git
      - run: iron-laws audit . --format sarif -o iron-laws.sarif || true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: iron-laws.sarif
      - run: iron-laws check . --fail-on HIGH

발견 사항이 있을 때도 SARIF 파일을 업로드할 수 있도록 보고서 생성 단계에서 || true를 사용합니다. 실제 통과 또는 실패 게이트는 마지막 check 명령이 제공합니다.

실질적인 제한 사항

  • 깨끗한 결과는 구현된 규칙과 지원되는 분석 범위 내에서 문제가 발견되지 않았다는 의미입니다. 애플리케이션에 취약점이 없음을 증명하지는 않습니다.
  • 파일 간 입력 추적은 Python에서 실험적이며 다른 언어에서는 제한적으로 지원됩니다. 일부 흐름은 누락되거나 수동 검토가 필요한 것으로 보고될 수 있습니다.
  • 새니타이저는 HTML, SQL, 셸 명령 또는 경로처럼 보호하는 컨텍스트에서만 인식됩니다.
  • README에 따르면 패치 검증, 회귀 테스트 및 승인 추적은 아직 독립적인 평가나 실제 환경의 파일럿을 거치지 않았습니다.
  • 프로젝트가 인용한 OWASP Benchmark 결과는 여러 범주에서 개선을 보여 주지만, 안전하게 새니타이즈된 SQL 및 명령어 삽입 사례를 포함해 오탐이 여전히 존재합니다.
  • 패키지 저장소를 확인하지 않으면 이 도구는 조작된 모든 의존성을 안정적으로 식별할 수 없습니다. 대신 인기 패키지와 유사한 이름을 보고합니다.
  • 압축 파일과 생성된 파일은 건너뛰며, 그 사유는 skipped_files 아래에 기록됩니다.

자세한 내용은 저장소 문서의 패치 검증, 정확도 측정, 언어 및 규칙 지원, 보고서 형식을 참조하세요.

결론

Iron Laws는 숨겨진 보안 및 유지 관리 문제가 프로덕션 사고로 이어지기 전에 AI가 생성한 소프트웨어를 검토할 수 있는 구조화된 방법을 제공합니다. iron-laws check .로 시작하고, 설명을 검토하고, 수정 프롬프트를 생성하고, AI의 변경 사항을 검토한 다음 다시 스캔하세요. 프로젝트가 성숙함에 따라 구성, 기준선, SARIF 보고, 패치 영수증 및 사람의 승인을 추가하면 프로세스를 반복 가능하고 감사 가능하게 만들 수 있습니다.

이 프로젝트는 MIT 라이선스로 제공됩니다. 결과는 테스트, 수동 코드 검토 및 광범위한 보안 평가를 대체하기보다 보완하는 데 사용해야 합니다.