코드 감사
코드 감사는 실험 기능입니다.
코드 감사는 로컬 코딩 에이전트를 사용하여 프로젝트의 보안을 검토하는 기능입니다. 사이드바에서 프로젝트를 마우스 오른쪽 버튼으로 클릭하고 "실험 기능" → "코드 감사"를 선택한 다음 "새 감사"를 클릭합니다. "로컬 도우미"에서 "Codex" 또는 "Claude"를 선택하고, "모델", "사고 강도", "감사 범위"를 선택한 뒤 "감사 시작"을 클릭합니다. 보고서 페이지에는 스캔의 현재 단계가 표시됩니다. "도우미 세션"에는 에이전트의 원래 도구 호출, 분석 내용, 대기 중인 권한 요청이 표시되며, 이곳에서 요청에 응답해야 감사가 계속 진행됩니다. 보고서는 Codex Security가 결과를 봉인하면 표시됩니다.
감사는 프로젝트가 있는 컴퓨터에서 실행되며, 선택한 에이전트의 설치된 CLI를 기존 로그인, 설정, 권한 처리 방식 그대로 사용합니다("로컬 도우미의 로그인과 설정을 사용합니다. 별도의 모델 API 설정이 필요하지 않습니다."). VelaTerm은 감사 세션에만 Codex Security MCP 서버를 추가하며, 다른 MCP 서버는 그대로 두고, 모델 API를 직접 호출하지 않습니다. CLI가 설치되어 있고 로그인되어 있어야 하며, 계정 사용 한도를 넘지 않아야 합니다. CLI 자체 설정에서 모델 제공자를 선택할 수 있으며, VelaTerm은 이 설정을 변경하지 않습니다.
"코드 감사" 항목은 컬렉션에도 표시됩니다. 루트 폴더가 없는 컬렉션은 감사할 수 없습니다.
모델과 사고 강도
모델 목록은 새 세션 대화 상자에서 해당 에이전트에 사용하는 목록과 같으며, 에이전트의 기본 실행 인수를 반영하므로 실제 감사가 실행되는 방식과 일치합니다. "기본 모델"을 선택하면 에이전트 자체의 선택을 따릅니다. "사고 강도"는 사고 강도를 지원하는 모델을 선택하면 사용할 수 있으며, "자동"을 선택하면 에이전트 자체의 선택을 따릅니다. 목록을 불러올 수 없으면 다시 시도 버튼이 표시됩니다. 백엔드는 명시적으로 지정한 조합을 검사하며, 감사는 선택한 값을 기록과 이후 실행에 사용하도록 저장합니다. 목록에 모델이 표시되더라도 계정에서 그 모델을 사용할 수 있다는 뜻은 아닙니다. 사용 한도 소진을 포함하여 제공자 측에서 오류가 발생하면 감사는 실패로 종료됩니다.
새 감사는 에이전트에게 인터페이스 언어로 분석을 작성하도록 요청합니다. 프로토콜 필드, 경로, 식별자, 인용된 소스 증거는 변경하지 않고 그대로 둡니다.
Codex Security 통합
VelaTerm에는 Apache-2.0 라이선스로 공개된 @openai/codex-security@0.1.26 릴리스가 포함되어 있으며, 이 릴리스의 플러그인 매니페스트 버전은 0.1.95입니다. 새 감사 페이지에는 두 버전이 모두 표시됩니다. 원본 스킬, 참고 문서, 스키마, 스크립트, 런타임, 라이선스가 포함되어 있으며, UPSTREAM.json에는 패키지 출처, 무결성 값, 파일 해시가 기록되어 있습니다.
새 감사마다 업스트림 워크벤치에 실제 스캔이 등록됩니다. 에이전트는 포함된 진입 스킬을 읽고 업스트림 MCP 도구와 결과 형식을 사용합니다. 이전에 독자적으로 구현했던 일괄 처리 워크플로의 기록은 계속 읽을 수 있으며, "이전 방식의 감사 · 이 기록에는 Codex Security 절차가 사용되지 않았습니다."라는 레이블이 표시됩니다.
두 에이전트는 같은 업스트림 워크플로를 사용합니다. 공개된 TypeScript SDK는 Codex 런타임을 구동하며 Claude Code 실행기를 제공하지 않으므로, VelaTerm은 업스트림 MCP 서버와 로컬 워크벤치를 통해 통합합니다. Claude Code 지원은 VelaTerm이 제공하는 어댑터이며, 업스트림이 Claude를 공식 지원한다는 뜻은 아닙니다.
런타임을 실행하려면 업스트림 패키지가 지원하는 버전의 Node.js가 PATH에 있어야 하고, Python 3.10 이상이 필요합니다. Python 3.10에서는 tomli 패키지도 필요하며, Python 3.11 이상에서는 내장된 tomllib이 이를 대신합니다. VelaTerm은 포함된 리소스를 확인한 뒤 자체 데이터 디렉터리에 압축을 풉니다. 이 리소스를 Codex나 Claude 설정에 설치하지는 않습니다.
감사 범위와 워크플로
- 전체 저장소는 대상의 고정된 스냅샷과 저장소의 보안 정책을 기준으로 업스트림 Standard 스캔을 실행합니다.
- 디렉터리 또는 파일은 정확한 "상대 경로"를 지정하여 Standard 스캔을 실행합니다. 호출 체인을 이해하기 위해 다른 소스 파일을 읽을 수도 있지만, 그 영역까지 전체 감사를 받았다고 간주하지는 않습니다.
- 작업 트리 변경 사항은 고정된 Git 변경 집합을 대상으로 업스트림 diff 스킬을 실행합니다. 업스트림 대상 확인 기능이 지원하는 스테이지된 변경 사항, 스테이지되지 않은 변경 사항, 추적되지 않는 변경 사항이 포함되며, 삭제된 파일에 대해서는 기준 증거를 보존합니다.
Standard 스캔은 skills/security-scan/SKILL.md와 references/core-scan.md를 읽습니다. 이 스캔은 실행 전 점검, 독립적인 기준선 및 아키텍처 분석, 소스 코드에 근거한 조사, 후보 체크포인트, 반대 증거 검토, 검증, 검토 범위 대조를 수행합니다. 에이전트가 지원하면 독립 작업자를 사용하고, 지원하지 않으면 업스트림의 순차 처리 대체 방식을 적용하며, 이 경우 그 한계를 밝혀야 합니다. 작업자 수 설정만으로는 독립 작업자가 실제로 실행되었다는 증거가 되지 않습니다.
작업 트리 감사는 skills/security-diff-scan/SKILL.md를 읽습니다. 이 감사는 대상을 고정하고, 위협 모델을 작성하고, 검토 항목을 준비하여 열거하고, 후보를 찾아 검증하고, 공격 경로를 분석한 다음, 결과 초안을 제출하여 완료합니다. 변경된 파일의 현재 내용만 검토하는 것으로는 이 절차를 대신할 수 없습니다.
업스트림 워크벤치는 디렉터리만 감사 범위로 받습니다. 파일 선택을 지원하기 위해 설치된 런타임에는 해시가 기록된 소규모 패치 두 개가 적용되어, 기존 파일을 감사 범위로 지정할 수 있고 이 파일은 스냅샷 항목 하나로 계산됩니다. 포함된 원본은 변경되지 않으며, 설치된 ADAPTER.json에는 원본 해시와 수정된 해시가 모두 기록됩니다. 파일을 선택했을 때 그 파일이 있는 디렉터리 전체를 스캔하는 일은 없습니다.
감사 지침은 소스 수정, 문제 수정, 게시, 에이전트 설정 변경을 금지합니다. 에이전트 자체의 도구 권한도 그대로 적용됩니다. 이 지침은 운영 체제 수준의 샌드박스가 아닙니다. 검증 결과에는 실제로 확인한 내용을 명시해야 하며, 정적 분석으로 발견한 문제가 곧 공격이 재현되었다는 뜻은 아닙니다("정적 검토만 수행합니다. 보고된 검토 범위가 모든 취약점의 발견을 보장하지는 않습니다. 동적 공격 재현은 수행하지 않습니다.").
보고서, 검토 범위, 취소
기준이 되는 결과는 업스트림의 scan-manifest.json, findings.json, coverage.json입니다. 업스트림 마무리 도구가 이 파일들을 검증하고 봉인한 다음, 읽기 쉬운 보고서를 생성합니다. VelaTerm은 이 파일들을 가져와 각 발견 사항의 위치와 정확한 소스 줄을 확인하며, 이때 LF와 CRLF 줄 끝은 같은 것으로 취급합니다. 구조가 올바르고 소스 줄이 일치한다는 사실만으로 발견 사항을 실제로 악용할 수 있다는 것이 증명되지는 않습니다. 소스 증거가 일치하지 않으면 감사는 "실패" 상태로 남고, 발견 사항은 검증된 것으로 인정되지 않습니다. 봉인된 업스트림 보고서는 계속 볼 수 있으며, Markdown으로 내보내면 보고서를 수정하지 않고 검증 실패 사실을 맨 앞에 표시합니다.
봉인하기 전에 VelaTerm은 가져오기에 사용하는 것과 같은 검증기로 초안의 경로, 줄 범위, 발췌 내용을 확인합니다. 증거가 일치하지 않으면 스캔은 봉인되지 않은 상태로 남고, 에이전트에게 수정해야 할 위치를 알려 줍니다. 그다음 Codex Security의 완료 도구가 보고서를 생성하고 봉인합니다. 이 확인 과정에서 발췌 내용을 다시 쓰거나, 발견 사항을 삭제하거나, 봉인된 결과를 변경하는 일은 없습니다. 가져올 때도 같은 확인을 반복하므로, 나중에 소스가 바뀌더라도 유효하지 않은 증거가 모르는 사이에 성공 결과로 바뀌지 않습니다.
검토 범위는 에이전트가 읽었다고 주장하는 파일 수가 아니라 업스트림의 검토 기록과 판정을 바탕으로 산출됩니다. 해결되지 않은 후보, 미뤄 둔 작업, 제외 항목, 완료 경고는 계속 표시됩니다. 검토 범위가 완전하지 않은 상태로 봉인된 스캔은 "일부 범위만 검토됨"으로 표시됩니다. 검토 범위가 완전하더라도 모든 취약점을 발견했다고 보장할 수는 없습니다.
스캔에 남은 작업이 있는데 에이전트가 턴을 끝내면, VelaTerm은 기존 발견 사항과 작업자 결과를 유지한 채 같은 세션과 스캔을 이어서 진행합니다. 권한 요청은 대기 상태로 남아 있으며("권한 승인 또는 입력 필요"), 취소하거나 제공자 오류가 발생하면 자동 진행이 중지됩니다. 업스트림의 검토 진행 상황, 발견 사항, 검토 범위에 아무 변화 없이 세 번 연속으로 턴이 끝나면, 감사는 스캔 미완료 오류와 함께 중지되며 체크포인트는 보존됩니다.
"보고서" 탭에는 저장된 발견 사항, 소스 증거, 검토 범위의 한계가 표시됩니다. 각 발견 사항에는 고유한 URL이 있으며, 공격 경로, 검증 방법과 결론(제공된 경우), 수정 권고, 보고된 소스 발췌가 표시됩니다. 이 발췌를 검증된 내용으로 받아들이기 전에 감사 상태를 확인하십시오. "보고서 산출물" 탭에는 업스트림이 생성한 전체 보고서와 스캔 ID가 보관됩니다. 실행 중인 스캔에는 업스트림 패키지 및 플러그인 버전, 실제 단계와 진행 상황, 경고가 표시되며, 봉인된 보고서가 생기기 전까지는 빈 평가 대신 진행 상황과 체크포인트 정보가 표시됩니다. "도우미 세션"에서는 관련 없는 턴이 감사를 대체하지 못하도록 일반 메시지 입력란과 되돌리기가 비활성화되며, 권한 요청에는 계속 응답할 수 있습니다.
"취소"는 업스트림 스캔과 에이전트를 중지합니다. 업스트림 워크벤치가 저장된 체크포인트를 봉인할 수 있으면 체크포인트를 계속 볼 수 있으며, 체크포인트는 취소됨 또는 실패 상태를 유지합니다. 뒤늦게 도착한 결과로 취소된 감사가 다시 진행되지는 않습니다. VelaTerm은 다시 시작한 뒤 업스트림 상태와 대조합니다. 완료되어 봉인된 결과는 가져올 수 있고, 끝나지 않은 실행은 "중단됨"으로 표시되며, 이 실행에서 보존된 파일은 완료된 결과와 구별됩니다.
기존 기록에서 "감사 시작"을 클릭하면 저장된 에이전트와 선택 사항으로 현재 대상을 새로 스캔합니다. 중지된 모델 턴을 재개하거나 이전 판정을 재사용하지는 않습니다.
감사 기록, 새 감사 양식, 보고서 세부 정보, 도우미 세션에는 각각 고유한 URL이 있으므로 직접 열거나 새로 고칠 수 있고, 브라우저의 뒤로 및 앞으로 버튼으로 이동할 수 있습니다. 좁은 화면에서는 기록과 세부 정보가 별도의 보기로 표시됩니다.
내보내기와 제한 사항
"보고서 내보내기"에서는 Markdown과 JSON 형식을 선택할 수 있습니다. Markdown으로 내보낸 파일에는 업스트림 보고서가 있으면 그 보고서가 들어가고, 없으면 완료되지 않은 스캔의 기록이라는 점이 명확히 표시됩니다. JSON으로 내보낸 파일에는 가져온 모든 데이터와 VelaTerm 자체 메타데이터가 함께 들어갑니다. 업스트림 스캔 폴더에는 생성된 SARIF 파일과 그 밖의 파일도 보관됩니다. 내보낸 파일에는 소스 발췌와 취약점 세부 정보가 포함될 수 있으므로 신중하게 공유하십시오.
이 인터페이스에서는 Standard 감사와 작업 트리 diff 감사를 제공합니다. 심층 스캔, 문제 수정, 수정 검증, 외부 이슈 추적 등 포함된 다른 스킬은 업스트림 리소스로 보관되어 있지만 별도의 작업으로 제공되지는 않습니다. 감사는 수정 사항을 적용하거나, 발견 사항을 게시하거나, 이슈를 만들거나, 풀 리퀘스트를 열지 않습니다.
진단
백엔드는 감사의 수명 주기와 업스트림 단계 정보를 애플리케이션 로그 디렉터리의 runtime-*.log에 기록합니다. VLX_LOG_DIR은 공통 로그 위치를 지정하며, 이 변수가 설정되지 않은 경우 VLX_SECURITY_LOG_DIR로 감사 이벤트의 로그 위치를 지정합니다. VLX_SECURITY_LOG_LEVEL=error로 설정하면 실패만 기록하고, off로 설정하면 기록하지 않습니다. 프롬프트와 응답은 크기와 SHA-256 다이제스트로만 기록되며, 전체 소스 코드, 자격 증명, 전체 AI 응답은 로그에 복사되지 않고, 제공자의 원본 메시지도 보관하지 않습니다. 사용자 지정 모델 이름은 현재 프로세스에서만 유효한 익명 식별자로 대체됩니다. 토큰 수가 표시되는 경우 세션의 누적 사용량을 나타냅니다. 에이전트의 대화는 평소와 같이 기록됩니다.
감사가 실패하면 보고서에 표시된 제공자의 설명을 읽거나 "도우미 세션"을 엽니다. 다른 감사를 시작하기 전에 로그인, 런타임, 권한, 계정 한도 문제를 해결하십시오. MCP 서버가 연결되어 있다는 것은 도구를 사용할 수 있다는 뜻일 뿐, 모델이 스캔을 완료했다는 뜻은 아닙니다.