AgentLint
코딩 에이전트가 작동하는 동안 위험한 동작을 포착합니다.
AgentLint는 제안된 파일 변경 사항과 셸 명령어(shell commands)를 로컬에서 확인합니다. 이 도구는 감지된 비밀 정보 쓰기(secret writes)와 main 또는 master 브랜치에 대한 평문 강제 푸시(plain force-pushes)를 차단하고, 위험한 작업에 대해 경고하며, 에이전트가 조치를 취할 수 있는 피드백을 제공합니다.
PyPI
CI
codecov
Downloads
GitHub stars
Python
License: MIT
Quickstart · Documentation · Integration coverage · Rules
A proposed credential write is blocked, the agent receives a correction, and a revised proposal is checked again.
지원되는 pre-tool 훅과 표준 정책을 사용한 일러스트레이션입니다. AgentLint는 수정된 제안을 다시 평가하며, 코드를 직접 재작성하지 않습니다.
<a id="what-a-block-looks-like"></a>
차이점을 확인해 보세요 (See the difference)
코딩 에이전트가 config.py에 자격 증명(credential)을 넣자고 제안하는 상황을 가정합니다. 이때 no-secrets 규칙은 해당 쓰기를 거부하고 다음과 같은 이유를 반환합니다:
[no-secrets] Secret assignment detected: api_key=...
-> Use environment variables instead of hard-coded secrets.
에이전트는 이 문자열 리터럴을 환경 변수 조회(environment-variable lookup)로 대체할 수 있습니다:
import os
api_key = os.environ["SERVICE_API_KEY"]
자격 증명 찾는 과정이 해결되었습니다. 수정된 동작은 활성 정책에 대해 확인되며, 다른 발견 사항들도 여전히 적용됩니다.
53초 분량의 제품 개요 영상 보기. 이 데모는 합성된 제안 동작을 데이터로 평가할 뿐, 위험한 명령을 실행하지 않습니다.
<a id="install"></a>
시작하기 (Get started)
Python 3.11 이상 및 pipx 또는 uv가 필요합니다.
uv tool install agentlint
cd your-project
agentlint setup claude
마지막 명령어에는 에이전트 이름을 사용하세요:
| Agent | Setup | Activate |
|---|
| Claude Code | agentlint setup claude | Claude Code 재시작 |
| ... | | |
pipx를 선호하나요? 대신 pipx install agentlint를 사용하세요. 설정(Setup)은 에이전트의 설정에 훅(hooks)을 추가하고, 프로젝트에서 감지된 패키지를 사용하여 agentlint.yml 파일이 존재하지 않으면 생성합니다.
에이전트에서 도구 호출을 한 번 수행한 다음, 다음 명령어를 실행하세요:
이 프로젝트에서 최근 관찰된(observed) 훅 호출을 확인하세요. 구성 파일만으로는 훅이 실행되고 있음을 증명할 수 없습니다. 아무것도 관찰되지 않으면 agentlint doctor를 실행하고 문제 해결(troubleshooting)을 따르세요.
5분 퀵스타트(quickstart)를 완료하면 첫 번째 확인 및 수정이 이루어집니다. Claude Code 사용자는 대신 마켓플레이스 플러그인(marketplace plugin)을 설치할 수 있습니다. 중복된 훅을 방지하려면 플러그인 또는 네이티브 설정을 사용하세요.
<a id="what-it-checks"></a>
무엇이 차단하고, 무엇이 경고하는가 (What blocks, what warns)
표준 심각도(severity) 및 관련 사전 도구 훅(pre-tool hook)과 함께:
| 결과 | 예시 | 요구 사항 |
|---|
| 차단(Block) | 감지된 비밀 쓰기, .env 쓰기, main/master에 대한 일반 --force/-f 푸시, CI 파이프라인 편집, 패키지 게시 | 핵심 규칙. 구성 및 각 규칙의 범위에 따라 달라짐 |
| ... | | |
일부 규칙은 도구 호출 후 또는 세션 종료 시 실행되므로 이미 발생한 작업을 방지할 수 없습니다. 심각도 설정(Severity settings), 승인(approvals), 면제(exemptions), 그리고 회로 차단기(circuit breaker)가 결정에 영향을 미칩니다. 규칙 참조(rule reference)는 정확한 동작을 문서화합니다.
통합이 중요합니다. 네이티브 훅(hooks)은 호스트가 보고하는 도구를 검사합니다. OpenAI Agents SDK adapter는 지원되는 도구에 연결되어야 합니다. MCP 서버는 온디맨드(on-demand) 검사를 제공하며 자문적입니다 (advisory). 통합에 의존하기 전에 [커버리지 및 제한 사항]을 확인하십시오.
AgentLint는 8개의 팩(packs)에 걸쳐 77개의 내장 규칙을 포함합니다:
| Pack | Rules | Examples |
|---|
| universal | 24 | secrets, .env writes, force-push, destructive commands, CI/CD edits, package publishing, test weakening |
| ... | | |
| 규칙 카탈로그는 각 규칙의 이벤트, 심각도 및 구성을 나열합니다. | | |
<a id="configure"></a>
프로젝트에 맞게 구성하기
packs: [python, security]
rules:
...
명시적인 packs 목록이 스택 감지를 대체합니다. universal 및 quality 팩은 의도적으로 제외되지 않는 한 포함됩니다. 감지된 기본값으로 시작하고 필요할 때 더 엄격한 팩을 추가하십시오.
| 원하는 작업 | 여기서 시작하기 |
|---|
| 일반적인 Git 작업을 유지하면서 공유 브랜치를 보호하려면 | main 보호 |
| ... | |
| <a id="day-to-day-commands"></a> | |
| <a id="more"></a> | |
에이전트 외부에서도 동일한 검사 사용하기
agentlint check-patch change.patch
agentlint ci --diff origin/main...HEAD
agentlint evidence
...
CI는 파일 변경 사항을 검사하며, 에이전트가 실행한 모든 셸 명령어를 재구성하거나 감사하지 않습니다. CI 설정 · CLI 참조
<a id="faq"></a>
기본적으로 로컬 환경에서 작동합니다
훅(Hook) 검사는 로컬에서 실행됩니다. 오프라인 규칙을 사용하려면 계정이나 네트워크 연결이 필요하지 않습니다. 선택적 기능인 AgentChute는 위협 피드, 팀 정책 및 가시성을 추가하며, 피드 기반 규칙은 해당 데이터가 필요합니다. 클라우드 이벤트 전송은 옵트인(opt-in) 방식이며 파일 내용이나 전체 명령 대신 수정된 요약본을 전송합니다.
AgentLint는 규칙(rules)과 휴리스틱스(heuristics)를 사용합니다. 위험한 동작을 놓칠 수 있고, 합법적인 작업에 플래그를 지정할 수 있으며, 광범위한 접근 권한을 가진 프로세스에 의해 우회될 수 있습니다. 코드 검토(code review), 테스트, CI(지속적 통합), 그리고 최소 권한 원칙(least-privilege) 자격 증명을 유지하십시오. 보안 모델 · 취약점 보고
<a id="contributing"></a>
기여(Contribute)
CONTRIBUTING.md부터 시작하세요. 오탐지(false positive) 또는 탐지 누락에 대한 회귀 사례(regression case)가 유용한 첫 기여입니다. AgentLint는 8개의 패키지에 77개의 내장 규칙을 포함하고 있으며, 카탈로그는 코드로부터 부분적으로 생성되어 CI에서 확인됩니다.
<a id="license"></a>
Changelog · Issues · Security policy · MIT license
Star history
AgentLint star history
