NuGuard 오픈 소스

NuGuard는 오픈 소스 AI 애플리케이션 보안 툴킷입니다. 그 목표는 에이전틱 AI 애플리케이션에 대해 가장 광범위한 레드팀 및 동작 검증을 제공하는 것입니다.

NuGuard를 사용하면 AI 개발자는 애플리케이션 구축에 집중할 수 있으며, NuGuard는 공급망 공격, 프롬프트 인젝션, MCP 도구 오용, API 공격, 데이터 유출 등 다양한 보안 위험에 대해 지속적으로 테스트하고 검증합니다. NuGuard를 통해 개발자는 보안 워크플로를 가속화하고 더 빠르게 자신 있게 프로덕션에 도달할 수 있습니다.

NuGuard의 상용 버전은 추가 기능과 지원을 갖춘 SaaS 제품으로 제공되며, http://nuguard.ai 에서 확인할 수 있습니다.

주요 기능

로컬 코드베이스 또는 Git 저장소에서 AI-SBOM 생성
구조적 AI 보안 위험 및 공급망 문제에 대해 SBOM 분석
SBOM을 기반으로 AI 동작 정책 제안
AI-SBOM 및 동작 정책을 중심으로 목적에 맞게 구축된 정적 및 런타임 동작 테스트 수행
샌드박스 처리된 AI 애플리케이션에 대한 레드팀 수행: 가장 광범위하고 최신으로 업데이트된 공격 벡터 카탈로그와 맞춤 제작 시나리오 제공. 여기에는 프롬프트 인젝션, 도구 남용, 데이터 유출, 그리고 대상 시스템의 다양한 서브 에이전트, 도구, 기능을 시험하는 관련 공격 시나리오가 포함됩니다.
발견된 문제에 대한 자동화된 수정 제안(코드 스니펫 및 정책 조정 포함)
발견 사항을 텍스트, JSON, Markdown 및 SARIF 지향 워크플로로 내보내기

현재 CLI 구성

현재 구현되어 사용 가능한 명령:

nuguard sbom
nuguard analyze
nuguard scan
nuguard policy
nuguard behavior
nuguard redteam

요구 사항

Python 3.12+
권장 로컬 워크플로를 위한 uv

설치

Python CLI:

pip install nuguard

아래 단계는 로컬 개발 환경을 설정하는 방법을 설명합니다. 최신 코드를 실행하거나, 프로젝트에 기여하거나, 로컬 환경 변수 구성이 필요한 LLM 지원 기능과 함께 CLI를 실행하려는 경우 이 방법을 권장합니다.

uv sync --dev

CLI를 다음과 같이 실행합니다:

uv run nuguard --help

또는 가상 환경에서:

. .venv/bin/activate
nuguard --help

Claude 사용자는 플러그인 명령을 사용할 수 있습니다.

docs/plugin-guide.md의 지침에 따라 Claude용 NuGuard 플러그인을 설정하고, 이를 사용하여 Claude와의 대화에서 /nuguard-sbom, /nuguard-analyze, /nuguard-redteam과 같은 명령을 직접 실행하세요.

빠른 시작

1. AI-SBOM 생성

nuguard sbom generate --source . --output app.sbom.json

원격 저장소를 스캔할 수도 있습니다:

nuguard sbom generate \
  --from-repo https://github.com/org/repo \
  --ref main \
  --output app.sbom.json

2. 정적 분석 실행

nuguard analyze --sbom app.sbom.json --format markdown

일반적인 출력:

사람이 검토하기 위한 markdown
자동화를 위한 json
코드 스캐닝 파이프라인을 위한 sarif

3. 동작 테스트

nuguard behavior \
  --sbom app.sbom.json \
  --target http://localhost:3000 \
  --format markdown

4. 라이브 앱 레드팀 수행

nuguard redteam \
  --config nuguard.yaml \
  --output reports/redteam.md \
  --format markdown

더 풍부한 레드팀 커버리지를 위해 다음을 제공할 수도 있습니다:

--policy를 사용한 인지 정책
--canary를 사용한 카나리 값
--config를 사용한 구성 파일

5. 통합 파이프라인 실행

nuguard scan \
  --source . \
  --output-dir nuguard-reports

기본적으로 이는 SBOM 생성과 정적 분석을 한 번에 실행합니다. 정책 및 레드팀 검증을 포함하려면 해당 단계를 선택하고 필요한 입력을 제공하세요:

nuguard scan \
  --source . \
  --steps sbom,analyze,policy,redteam \
  --policy cognitive_policy.md \
  --target http://localhost:3000 \
  --output-dir nuguard-reports

구성

NuGuard는 nuguard.yaml을 통한 프로젝트 구성을 지원합니다. 바로 편집할 수 있는 예제는 nuguard.yaml.example에 있습니다.

예제 구성의 주요 영역:

sbom: 기존 SBOM 경로
source: 생성을 위한 소스 디렉터리
policy: 인지 정책 경로
llm: LLM 지원 기능을 위한 모델 설정
behavior: 행위 테스트를 위한 대상 URL, 엔드포인트, 테스트 프로필 설정
redteam: 대상 URL, 엔드포인트, 카나리 파일, 프로필, 시나리오 필터, 가이드 대화 설정, 발견 트리거 제어(finding_triggers.*)
analyze: 최소 심각도 임계값
database: SQLite 또는 Postgres 기반 저장소 설정
output: 출력 형식 및 실패 임계값

CLI 플래그는 nuguard.yaml보다 우선하며, nuguard.yaml은 환경 변수와 내장 기본값보다 우선합니다.

레드팀 카나리

NuGuard는 동적 테스트 중에 심어둔 카나리 값을 감시하여 신뢰도 높은 유출 발견 결과를 생성할 수 있습니다. canary.example.json에서 시작하여 로컬 canary.json을 만들고, 해당 값을 대상 시스템에 심은 다음, --canary로 nuguard redteam이 해당 파일을 가리키도록 설정하세요.

자세한 내용은 docs/redteam-engine.md에서 확인할 수 있습니다.

개발

개발 의존성 설치:

make dev

테스트 실행:

make test

린트 및 타입 검사 실행:

make lint

코드베이스 형식을 지정합니다:

make fmt

게시

이 저장소에는 TestPyPI 및 PyPI로의 신뢰할 수 있는 게시(Trusted Publishing)를 위한 GitHub Actions 워크플로가 포함되어 있습니다:

워크플로가 게시를 수행하기 전에, TestPyPI와 PyPI에서 nuguard 프로젝트에 대해 다음 항목으로 신뢰할 수 있는 게시자(Trusted Publisher)를 구성하세요:

소유자/조직: NuGuardAI
저장소: nuguard
워크플로 파일: publish-testpypi.yml 또는 publish-pypi.yml
환경: testpypi 또는 pypi

권장 릴리스 흐름:

GitHub Actions에서 TestPyPI 워크플로를 수동으로 실행합니다.
TestPyPI에서 패키지 설치 및 CLI 동작을 검증합니다.
GitHub 릴리스를 생성하여 PyPI 게시 워크플로를 트리거합니다.

게시 전 정상 작동 점검

TestPyPI 또는 PyPI에 게시하기 전에, 빠른 다중 앱 정상 작동 점검 게이트를 실행하세요.

원샷 러너:

bash tests/apps/prepublish-sanity.sh

이 러너는 다음을 수행합니다:

빠른 저장소 스모크 검사(nuguard --help 및 핵심 로컬 테스트)
intent_happy_path 워크플로를 사용한 동적 모드의 동작 실행
profile: ci를 사용한 레드팀 실행
아티팩트 및 품질 게이트(비어 있지 않은 보고서, 실행된 시나리오 수가 0이 아님, 엄격한 엔드포인트 소스 검사, 전송 오류 가드레일)

러너가 사용하는 사전 게시(publish 전) 구성 파일:

tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml
tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml
tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml

앱별로 수동 실행(필요한 경우):

# OpenAI CS agents demo
uv run nuguard sbom generate --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --format json -o tests/apps/openai-cs-agents-demo/openai-cs.sbom.json
uv run nuguard behavior --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/openai-cs-agents-demo/reports/openai-cs-prepublish-behavior --verbose
uv run nuguard redteam --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --format json --format markdown --output tests/apps/openai-cs-agents-demo/reports/openai-cs-prepublish-redteam --verbose

# Gemini Auto app
uv run nuguard sbom generate --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --format json -o tests/apps/Gemini-Auto-app/gemini-auto.sbom.json
uv run nuguard behavior --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/Gemini-Auto-app/reports/gemini-auto-prepublish-behavior --verbose
uv run nuguard redteam --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --format json --format markdown --output tests/apps/Gemini-Auto-app/reports/gemini-auto-prepublish-redteam --verbose

# Pinnacle Bank app
uv run nuguard sbom generate --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --format json -o tests/apps/pinnacle-bank-app/pinnacle-bank.sbom.json
uv run nuguard behavior --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/pinnacle-bank-app/reports/pinnacle-bank-prepublish-behavior --verbose
uv run nuguard redteam --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --format json --format markdown --output tests/apps/pinnacle-bank-app/reports/pinnacle-bank-prepublish-redteam --verbose

중요:

publish-gating 실행에서는 || true를 사용하지 마십시오.
종료 코드 2는 발견 사항 또는 정책 게이트를 나타낼 수 있습니다. 이를 신호로 간주하고, 통과/실패를 결정할 때는 보고서 품질 검사를 신뢰하십시오.

저장소 참고 사항

저장소에는 현재 tests/output/ 아래에 예시 출력과 벤치마크 픽스처가 포함되어 있습니다
일부 레드팀 및 벤치마크 테스트는 선택 사항이며 환경 변수로 게이트됩니다
LLM 지원 기능은 환경 변수를 통해 제공되는 공급자 자격 증명에 의존합니다

라이선스

라이선스 정보는 LICENSE 파일에서 확인할 수 있습니다.

nuguard

인기