Cycode

공식

개발 라이프사이클에서 SAST, SCA, 시크릿 및 IaC 스캐닝을 통해 보안을 강화하세요.

GitHub

Cycode MCP(으)로 무엇을 할 수 있나요?

비밀 정보 스캔 — cycode_secret_scan을 사용해 하드코딩된 비밀 정보가 있는지 파일이나 디렉터리를 스캔하도록 어시스턴트에 요청합니다.
SCA 문제 스캔 — cycode_sca_scan을 통해 취약점 및 라이선스 문제를 확인하는 소프트웨어 구성 분석 스캔을 요청합니다.
IaC 구성 오류 스캔 — cycode_iac_scan을 사용해 코드형 인프라의 구성 오류를 확인하도록 어시스턴트에 요청합니다.
SAST 문제 스캔 — cycode_sast_scan을 사용해 코드 품질 및 보안 결함을 확인하는 정적 애플리케이션 보안 테스트 스캔을 실행합니다.
CLI 상태 확인 — cycode_status를 통해 Cycode CLI 버전, 인증 상태 및 구성 세부 정보를 요청합니다.

문서

Cycode CLI 사용자 가이드

Cycode 명령줄 인터페이스(CLI)는 로컬에 설치하여 저장소에서 시크릿, 코드형 인프라 구성 오류, 소프트웨어 구성 분석 취약점 및 정적 애플리케이션 보안 테스트 문제를 검사할 수 있는 애플리케이션입니다.

이 가이드에서는 설치와 사용 방법을 모두 안내합니다.

사전 요구 사항

Cycode CLI 애플리케이션을 사용하려면 Python 버전 3.10 이상이 필요합니다.
CLI로 Cycode에 인증하려면 cycode auth 명령을 사용하세요.
- 또는 서비스 계정 토큰 및 개인 액세스 토큰 페이지에 설명된 단계를 따라 Cycode Client ID와 Client Secret Key를 발급받을 수 있습니다. 해당 페이지에서 이 값을 얻는 방법을 자세히 확인할 수 있습니다.

설치

다음 설치 단계는 Windows와 UNIX / Linux 운영 체제 모두에 적용됩니다.

[!NOTE] 다음 단계에서는 Python 관련 명령에 python3 및 pip3을 사용한다고 가정합니다. 하지만 Python 환경 구성에 따라 일부 시스템에서는 python 및 pip 명령을 사용할 수도 있습니다.

Cycode CLI 설치

로컬 컴퓨터에 Cycode CLI 애플리케이션을 설치하려면 다음 단계를 수행하세요.

명령줄 또는 터미널 애플리케이션을 엽니다.
다음 명령 중 하나를 실행합니다.
- PyPI에서 설치하려면:
```
pip3 install cycode
```
- Homebrew에서 설치하려면:
```
brew install cycode
```
- GitHub Releases에서 설치하려면 해당 페이지로 이동하여 운영 체제와 아키텍처에 맞는 실행 파일을 다운로드한 다음 다음 명령을 실행합니다.
```
cd /path/to/downloaded/cycode-cli
chmod +x cycode
./cycode
```
마지막으로 CLI를 인증합니다. Cycode 클라이언트 ID와 자격 증명(클라이언트 시크릿 또는 OIDC ID 토큰)을 설정하는 방법은 세 가지입니다.
- cycode auth (권장)
- cycode configure
- 환경 변수에 추가

Auth 명령 사용

[!NOTE] 이 방법은 로컬 컴퓨터에서 Cycode CLI 인증을 설정하는 권장 방법입니다.

터미널/명령줄 창에 다음 명령을 입력합니다.

cycode auth
Cycode에 로그인하라는 브라우저 창이 나타납니다(아래 참조).
이 페이지에서 로그인 자격 증명을 입력하고 로그인합니다.
그러면 아래 페이지로 이동하여 Cycode를 인증할 비즈니스 그룹을 선택하라는 메시지가 표시됩니다(해당하는 경우).

[!NOTE] 이 설정은 Cycode CLI 인증의 기본 방법이 됩니다.
Allow 버튼을 클릭하여 선택한 비즈니스 그룹에서 Cycode CLI를 인증합니다.
선택이 성공적으로 완료되면 다음 화면이 표시됩니다.
브라우저 창을 닫으면 터미널/명령줄 화면에 다음 내용이 표시됩니다.

Successfully logged into cycode

Configure 명령 사용

[!NOTE] Linux 또는 Windows 환경 변수를 통해 Cycode Client ID와 Client Secret을 이미 설정한 경우, 해당 자격 증명이 이 방법보다 우선 적용됩니다.

터미널/명령줄 창에 다음 명령을 입력합니다.
```
cycode configure
```
Cycode API URL 값을 입력합니다(기본값을 사용하려면 비워 둘 수 있습니다).

Cycode API URL [https://api.cycode.com]: https://api.onpremise.com
Cycode APP URL 값을 입력합니다(기본값을 사용하려면 비워 둘 수 있습니다).

Cycode APP URL [https://app.cycode.com]: https://app.onpremise.com
Cycode Client ID 값을 입력합니다.

Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d
Cycode Client Secret 값을 입력합니다(OIDC ID 토큰을 사용할 예정이면 건너뜁니다).

Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e
Cycode OIDC ID Token 값을 입력합니다(선택 사항).

Cycode ID Token []: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
값을 성공적으로 입력하면 다음 메시지가 표시됩니다.

Successfully configured CLI credentials!

또는/그리고

Successfully configured Cycode URLs!

사용자 폴더 아래의 .cycode 폴더로 이동하면 자격 증명이 생성되어 해당 폴더의 credentials.yaml 파일에 저장된 것을 확인할 수 있습니다. URL은 해당 폴더의 config.yaml 파일에 저장됩니다.

환경 변수에 추가

Unix/Linux에서:

export CYCODE_CLIENT_ID={your Cycode ID}

및

export CYCODE_CLIENT_SECRET={your Cycode Secret Key}

조직에서 OIDC 인증을 사용하는 경우 ID 토큰을 대신 제공하거나 추가로 제공할 수 있습니다.

export CYCODE_ID_TOKEN={your Cycode OIDC ID token}

Windows에서

제어판에서 시스템 메뉴로 이동합니다.
그런 다음 고급 시스템 설정을 클릭합니다.
열리는 시스템 속성 창에서 환경 변수 버튼을 클릭합니다.
ID와 Secret Key에 해당하는 값을 사용하여 CYCODE_CLIENT_ID 및 CYCODE_CLIENT_SECRET 변수를 만듭니다. OIDC로 인증하는 경우 OIDC ID 토큰 값을 사용하여 CYCODE_ID_TOKEN도 추가합니다.
설치를 완료하려면 경로에 cycode.exe을 삽입합니다.

Pre-Commit Hook 설치

로컬 저장소에 Cycode의 pre-commit 및 pre-push hook을 설정하면 Cycode CLI 애플리케이션이 코드를 커밋하거나 코드베이스에 푸시하기 전에 코드의 문제를 자동으로 식별합니다.

[!NOTE] pre-commit 및 pre-push hook은 IaC 검사에서 사용할 수 없습니다.

pre-commit hook을 설치하려면 다음 단계를 수행하세요.

Pre-Commit Hook 설치

pre-commit 프레임워크를 설치합니다(Python 3.10 이상이 설치되어 있어야 합니다).
```
pip3 install pre-commit
```
구성하려는 로컬 Git 저장소의 최상위 디렉터리로 이동합니다.
저장소의 최상위 디렉터리에 .pre-commit-config.yaml이라는 새 YAML 파일을 만들고(시작 부분에 . 포함) 다음 내용을 입력합니다.
```
repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.25.0
    hooks:
      - id: cycode
        stages: [pre-commit]
```
필요에 맞게 생성한 파일을 수정합니다. 시크릿 검사를 활성화하려면 hook ID cycode을 사용합니다. SCA 검사를 활성화하려면 hook ID cycode-sca를 사용합니다. SAST 검사를 활성화하려면 hook ID cycode-sast을 사용합니다. 모든 검사 유형을 활성화하려면 다음 구성을 사용합니다.
```
repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.25.0
    hooks:
      - id: cycode
        stages: [pre-commit]
      - id: cycode-sca
        stages: [pre-commit]
      - id: cycode-sast
        stages: [pre-commit]
```
Cycode hook을 설치합니다.
```
pre-commit install
```
hook 설치가 성공하면 다음 메시지가 표시됩니다. Pre-commit installed at .git/hooks/pre-commit.
pre-commit hook을 최신 상태로 유지합니다.
```
pre-commit autoupdate
```
그러면 .pre-commit-config.yaml의 rev이 최신 Cycode CLI 버전으로 자동 업데이트됩니다.

[!NOTE] git commit 명령이 실행될 때 트리거됩니다. hook은 커밋을 위해 스테이징된 파일에 대해서만 실행됩니다.

Pre-Push Hook 설치

pre-commit hook과 함께 또는 대신 pre-push hook을 설치하려면 다음을 수행합니다.

.pre-commit-config.yaml 파일에 pre-push hook을 추가합니다.

repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.25.0
    hooks:
      - id: cycode-pre-push
        stages: [pre-push]

pre-push hook을 설치합니다.

pre-commit install --hook-type pre-push

pre-commit 및 pre-push hook을 모두 설치하려면 다음을 사용합니다.
```
pre-commit install
pre-commit install --hook-type pre-push
```

[!NOTE] Pre-push hook은 git push 명령이 실행될 때 트리거되며, 푸시할 예정인 커밋만 검사합니다.

Cycode CLI 명령

다음은 Cycode CLI 애플리케이션에서 사용할 수 있는 옵션과 명령입니다.

옵션	설명
`-v`, `--verbose`	자세한 로그를 표시합니다.
`--no-progress-meter`	진행률 표시기를 표시하지 않습니다.
`--no-update-notifier`	CLI 업데이트를 확인하지 않습니다.
`-o`, `--output [rich\|text\|json\|table]`	출력 유형을 지정합니다. 기본값은 `rich`입니다.
`--client-id TEXT`	이 검사 실행에 사용할 Cycode 클라이언트 ID를 지정합니다.
`--client-secret TEXT`	이 검사 실행에 사용할 Cycode 클라이언트 시크릿을 지정합니다.
`--id-token TEXT`	이 검사 실행에 사용할 Cycode OIDC ID 토큰을 지정합니다.
`--install-completion`	현재 셸에 자동 완성을 설치합니다.
`--show-completion [bash\|zsh\|fish\|powershell\|pwsh]`	지정한 셸의 자동 완성 설정을 표시하여 복사하거나 설치를 사용자 지정할 수 있습니다.
`-h`, `--help`	지정한 명령의 옵션을 표시합니다.
명령	설명
-------------------------------------------	----------------------------------------------------------------------------------------------------------------------------------------------
auth	CLI를 Cycode 계정에 연결하도록 컴퓨터를 인증합니다.
configure	CLI 클라이언트 인증을 구성하는 초기 명령입니다.
ignore	특정 값, 경로 또는 규칙 ID를 무시합니다.
mcp	Cycode 스캔 기능과 AI 통합을 지원하는 Model Context Protocol (MCP) 서버를 시작합니다.
scan	콘텐츠에서 Secrets/IaC/SCA/SAST 위반을 스캔합니다. 수행할 스캔 유형을 지정해야 합니다: commit-history/path/repository/etc.
report	보고서를 생성합니다. SBOM과 같이 수행할 보고서 유형을 지정해야 합니다.
status	CLI 상태를 표시하고 종료합니다.

인증서 및 프록시

기본적으로 Cycode CLI는 CLI와 함께 제공되는 CA 번들을 사용해 HTTPS 연결을 확인합니다.

조직에서 HTTPS 트래픽을 검사하는 프록시를 사용하거나 자체 CA가 있는 온프레미스 설치 환경을 사용하는 경우 두 가지 옵션이 있습니다.

옵션 1 — 컴퓨터에 이미 설치된 인증서를 사용합니다. CA가 컴퓨터의 인증서 저장소에 있는 경우(관리되는 장치에서 일반적으로 그렇듯이) 다음을 사용하도록 설정합니다.

export CYCODE_CLI_ENABLE_TRUSTSTORE=1

그러면 CLI는 Windows 인증서 저장소, macOS Keychain 또는 Linux의 시스템 CA 디렉터리를 기준으로 확인하므로 인증서 경로를 구성할 필요가 없습니다.

[!IMPORTANT] 이 기능은 의도적으로 선택 사항입니다. 컴퓨터 저장소를 신뢰한다는 것은 해당 컴퓨터에 있는 모든 루트 인증서를 신뢰한다는 뜻이며, 여기에는 관리자나 악성 소프트웨어가 설치한 인증서도 포함됩니다. 컴퓨터의 인증서 저장소를 신뢰할 수 있다고 확신하는 경우에 사용하도록 설정하세요.

옵션 2 — CLI가 CA 번들 파일을 사용하도록 지정합니다. 별도의 설정 없이 사용할 수 있습니다.

환경 변수	설명
`REQUESTS_CA_BUNDLE`	신뢰할 CA 번들 파일(`.pem` 또는 `.crt`)의 경로입니다.
`CURL_CA_BUNDLE`	`REQUESTS_CA_BUNDLE`의 별칭이며, 후자가 설정되지 않은 경우 사용됩니다.

두 옵션은 함께 사용할 수 있습니다. CYCODE_CLI_ENABLE_TRUSTSTORE=1를 사용하면 REQUESTS_CA_BUNDLE의 인증서는 컴퓨터 저장소를 대체하는 것이 아니라 추가로 신뢰됩니다.

[!TIP] -v를 사용해 명령을 실행하면 사용 중인 신뢰 소스를 확인할 수 있습니다. 예: cycode -v status.

참고:

Windows에서는 REQUESTS_CA_BUNDLE 또는 CURL_CA_BUNDLE가 설정되지 않은 경우 CLI가 항상 시스템 인증서 저장소를 사용했습니다. 이 동작은 변경되지 않았습니다.
프록시 자체는 표준 HTTP_PROXY, HTTPS_PROXY, NO_PROXY 환경 변수를 사용해 구성합니다.

MCP 명령 [EXPERIMENT]

Model Context Protocol (MCP) 명령을 사용하면 Cycode의 스캔 기능을 AI 시스템과 애플리케이션에 제공하는 MCP 서버를 시작할 수 있습니다. 이를 통해 AI 모델은 표준화된 프로토콜을 통해 Cycode CLI 도구와 상호 작용할 수 있습니다.

[!TIP] 최상의 사용 환경을 위해 pip install cycode 또는 brew install cycode를 사용해 시스템에 Cycode CLI를 전역 설치한 다음, cycode auth으로 한 번 인증하세요. 전역 설치 및 인증을 마치면 MCP 구성 파일에서 CYCODE_CLIENT_ID 및 CYCODE_CLIENT_SECRET 환경 변수를 구성할 필요가 없습니다.

MCP 서버 시작

MCP 서버를 시작하려면 다음 명령을 사용합니다.

cycode mcp

기본적으로 서버는 stdio 전송 방식을 사용해 시작됩니다. 이 방식은 로컬 통합 및 하위 프로세스를 실행할 수 있는 AI 애플리케이션에 적합합니다.

사용 가능한 옵션

옵션	설명
`-t, --transport`	MCP 서버의 전송 유형: `stdio`, `sse` 또는 `streamable-http` (기본값: `stdio`)
`-H, --host`	서버를 바인딩할 호스트 주소(비 stdio 전송에서만 사용)(기본값: `127.0.0.1`)
`-p, --port`	서버를 바인딩할 포트 번호(비 stdio 전송에서만 사용)(기본값: `8000`)
`--help`	도움말 메시지와 사용 가능한 옵션을 표시합니다

MCP 도구

MCP 서버는 AI 시스템에서 사용할 수 있는 다음 도구를 제공합니다.

도구 이름	설명
`cycode_secret_scan`	하드코딩된 시크릿을 스캔합니다
`cycode_sca_scan`	Software Composition Analysis (SCA)를 스캔합니다. 취약점 및 라이선스 문제를 확인합니다
`cycode_iac_scan`	Infrastructure as Code (IaC) 구성 오류를 스캔합니다
`cycode_sast_scan`	Static Application Security Testing (SAST)을 스캔합니다. 코드 품질 및 보안 결함을 확인합니다
`cycode_status`	Cycode CLI 버전, 인증 상태 및 구성 정보를 가져옵니다

각 스캔 도구는 상호 배타적인 두 가지 입력 모드를 지원합니다.

paths (권장) — 디스크에 존재하는 하나 이상의 파일 또는 디렉터리 경로입니다. 디렉터리는 재귀적으로 스캔됩니다. Cycode 엔진은 CLI에서 cycode scan -t <type> path ./src가 수행하는 것과 마찬가지로 파일 검색 및 필터링을 처리합니다.
files (대체 방식) — 파일 경로를 전체 콘텐츠 문자열에 매핑하는 사전입니다. 파일을 디스크에서 사용할 수 없는 경우(예: 아직 저장하지 않은 메모리 내 편집 내용)에만 사용하세요.

[!TIP] 가능하면 paths를 사용하세요. 대용량 파일(예: package-lock.json)을 인라인 콘텐츠로 전달하면 토큰 제한을 초과하고 AI 클라이언트의 속도가 느려질 수 있습니다. paths를 사용하면 Cycode 엔진이 디스크에서 파일을 직접 읽습니다.

모든 스캔 도구는 전체 "detections" 배열 외에도 사람이 읽을 수 있는 위반 수(예: "Cycode found 3 violations: 1 CRITICAL, 2 HIGH.")를 포함하는 "summary" 필드가 있는 JSON 객체를 반환합니다.

사용 예시

기본 명령 예시

기본 설정(stdio 전송)으로 MCP 서버를 시작합니다.

cycode mcp

stdio 전송을 명시적으로 지정해 MCP 서버를 시작합니다.

cycode mcp -t stdio

Server-Sent Events (SSE) 전송으로 MCP 서버를 시작합니다.

cycode mcp -t sse -p 8080

사용자 지정 호스트와 포트에서 스트리밍 가능한 HTTP 전송으로 MCP 서버를 시작합니다.

cycode mcp -t streamable-http -H 0.0.0.0 -p 9000

MCP 전송 유형에 대한 자세한 내용은 MCP Protocol Specification – Transports를 참조하세요.

구성 예시

Cursor/VS Code/Claude Desktop 등에서 MCP 사용(mcp.json)

[!NOTE] EU Cycode 환경에서는 환경 변수에 적절한 CYCODE_API_URL 및 CYCODE_APP_URL 값을 설정해야 합니다(예: https://api.eu.cycode.com 및 https://app.eu.cycode.com).

이 가이드에 따라 VS Code/GitHub Copilot에서 MCP 서버를 구성하세요. settings.json에는 독립형 mcpServers 객체가 아니라 중첩된 servers 하위 객체를 포함하는 mcp 객체가 있다는 점에 유의하세요.

stdio 전송(직접 실행):

{
  "mcpServers": {
    "cycode": {
      "command": "cycode",
      "args": ["mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

pipx 설치를 사용한 stdio 전송:

{
  "mcpServers": {
    "cycode": {
      "command": "pipx",
      "args": ["run", "cycode", "mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

uvx 설치를 사용한 stdio 전송:

{
  "mcpServers": {
    "cycode": {
      "command": "uvx",
      "args": ["cycode", "mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

SSE 전송(Server-Sent Events):

{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

사용자 지정 포트에서의 SSE 전송:

{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8080/sse"
    }
  }
}

스트리밍 가능한 HTTP 전송:

{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

MCP 서버를 백그라운드에서 실행

SSE 전송(먼저 서버를 시작한 다음 클라이언트를 구성):

# Start the MCP server in the background
cycode mcp -t sse -p 8000 &

# Configure in mcp.json
{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

스트리밍 가능한 HTTP 전송:

# Start the MCP server in the background
cycode mcp -t streamable-http -H 127.0.0.2 -p 9000 &

# Configure in mcp.json
{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.2:9000/mcp"
    }
  }
}

고급 구성

시간 제한 및 사용자 지정 인증서(프록시 환경)

MCP 클라이언트가 장시간 실행되는 스캔을 중단하는 경우 도구 호출 시간 제한을 늘리세요.

환경 변수	설명
`MCP_TOOL_TIMEOUT`	Claude 및 GitHub Copilot과 같은 MCP 클라이언트가 도구 호출 완료를 기다리는 시간(초)입니다. 장시간 실행되는 스캔이 완료되기 전에 중단되는 경우 이 값을 늘리세요.

기업 프록시 환경에서는 MCP 서버의 env 블록에 인증서 변수를 설정하세요. 옵션은 인증서 및 프록시를 참조하세요. CYCODE_CLI_ENABLE_TRUSTSTORE=1을 사용해 컴퓨터에 이미 있는 인증서를 사용하거나, REQUESTS_CA_BUNDLE을 사용해 CA 번들 파일을 지정할 수 있습니다.

사용자 지정 CA 번들과 더 긴 시간 제한을 사용하는 mcp.json 구성 예시:

{
  "mcpServers": {
    "cycode": {
      "command": "cycode",
      "args": ["mcp"],
      "env": {
        "REQUESTS_CA_BUNDLE": "/path/to/your/corporate-ca-bundle.pem",
        "MCP_TOOL_TIMEOUT": "1800"
      }
    }
  }
}

[!NOTE] MCP 서버가 작동하려면 Cycode CLI 인증이 올바르게 설정되어 있어야 합니다. MCP 서버를 시작하기 전에 cycode auth을 사용해 인증했거나 자격 증명을 구성했는지 확인하세요.

하위 에이전트용 도구 사전 승인(Claude Code)

Claude Code가 백그라운드 하위 에이전트에 작업을 위임하는 경우(예: 스캔을 병렬로 실행하는 경우), 해당 하위 에이전트는 대화형 권한 프롬프트를 표시할 수 없습니다. Cycode 도구가 사전 승인되지 않았다면 하위 에이전트 컨텍스트에서 스캔이 아무런 알림 없이 실패합니다.

하위 에이전트를 포함한 모든 컨텍스트에서 Cycode MCP 도구를 사용할 수 있도록 사전 승인하려면 Claude Code 설정(~/.claude/settings.json)의 allowedTools 목록에 도구를 추가하세요.

{
  "allowedTools": [
    "mcp__cycode__cycode_secret_scan",
    "mcp__cycode__cycode_sca_scan",
    "mcp__cycode__cycode_iac_scan",
    "mcp__cycode__cycode_sast_scan",
    "mcp__cycode__cycode_status"
  ]
}

추가한 후에는 해당 도구를 호출할 때 Claude Code가 승인을 요청하지 않으며, 하위 에이전트 내에서도 정상적으로 작동합니다.

MCP 문제 해결

MCP 서버에 문제가 발생하면 디버그 로깅을 사용하도록 설정해 상황에 대한 자세한 정보를 확인할 수 있습니다. 디버그 로깅을 사용하도록 설정하는 방법은 두 가지입니다.

-v 또는 --verbose 플래그 사용:

cycode -v mcp

CYCODE_CLI_VERBOSE 환경 변수 사용:

CYCODE_CLI_VERBOSE=1 cycode mcp

디버그 로그에는 다음에 대한 자세한 정보가 표시됩니다.

서버 시작 및 구성
연결 시도 및 상태
도구 실행 및 결과
발생한 오류 또는 경고

이 정보는 다음과 같은 경우에 유용합니다.

연결 문제 진단
특정 도구가 작동하지 않는 이유 파악
인증 문제 식별
전송 방식별 문제 디버깅

MCP 구성

Platform 명령 [BETA]

[!WARNING] platform 명령은 베타 버전입니다. 명령, 인수 및 출력 형식은 Cycode API 사양에서 동적으로 생성되며, 예고 없이 릴리스 간에 변경될 수 있습니다. 아직 프로덕션 자동화에서 이에 의존하지 마세요.

cycode platform 명령은 Cycode 플랫폼의 읽기 API를 CLI 명령으로 제공합니다. 엔드포인트를 리소스별로 그룹화하고(예: projects, violations, workflows), 각 엔드포인트의 매개변수를 형식이 지정된 CLI 인수 및 --option 플래그로 변환합니다.

cycode platform projects list --page-size 50
cycode platform violations count
cycode platform workflows view <workflow-id>

OpenAPI 사양은 처음 사용할 때 Cycode API에서 가져와 ~/.cycode/openapi-spec.json에 24시간 동안 캐시됩니다. 관련 없는 명령(cycode scan, cycode status 등)은 가져오기를 실행하지 않습니다.

[!NOTE] cycode platform에서 명령을 검색하고 실행하려면 인증이 필요합니다(cycode auth 또는 CYCODE_CLIENT_ID / CYCODE_CLIENT_SECRET 환경 변수). 다른 Cycode CLI 명령은 인증 없이 사용할 수 있습니다.

명령 검색

명령은 사양에서 생성되므로 사용 가능한 항목의 기준 정보는 --help입니다.

cycode platform --help                  # list all resource groups
cycode platform projects --help         # list actions on a resource
cycode platform projects list --help    # list options/arguments for an action

플랫폼 예시

# List projects with pagination
cycode platform projects list --page-size 25

# View a single project by ID
cycode platform projects view <project-id>

# Count violations across the tenant
cycode platform violations count

# Filter using query parameters (see `--help` for what each endpoint supports)
cycode platform violations list --severity CRITICAL

기본적으로 모든 출력은 JSON입니다. 임시 필터링을 하려면 jq으로 파이프하세요.

cycode platform projects list --page-size 100 | jq '.items[].name'

플랫폼 참고 사항 및 제한 사항

현재 읽기 전용입니다. 이 베타에서는 GET 엔드포인트만 노출됩니다.
사양 기반입니다. API에 새 엔드포인트를 추가하면 다음에 캐시를 새로 고칠 때 자동으로 표시됩니다.
포함된 사양이 없습니다. 설치 후(또는 24시간 캐시가 만료된 후) 처음 실행하는 cycode platform 호출은 네트워크에서 데이터를 가져옵니다. 연결 속도가 느리면 첫 호출에 몇 초가 걸릴 수 있으며, 이후 호출은 캐시가 만료될 때까지 거의 즉시 완료됩니다.
CYCODE_SPEC_CACHE_TTL=<seconds>으로 캐시 TTL을 재정의할 수 있습니다.

AI 가드레일 [BETA]

AI 가드레일은 지원되는 AI 코딩 에이전트(Claude Code, Cursor, Copilot, Codex)에 후크를 설치하여 프롬프트, 에이전트가 읽는 파일, MCP 도구 인수에 비밀 정보가 있는지 모델에 전달되기 전에 검사합니다.

AI 가드레일에서 수집하는 데이터

검사는 서버 측에서 수행되므로 검사 대상 콘텐츠가 컴퓨터 외부로 전송됩니다. 프롬프트 텍스트, 에이전트가 읽는 파일의 내용, MCP 도구 인수가 비밀 정보 검사를 위해 Cycode 테넌트로 전송됩니다.

각 이벤트에는 개발자와 컴퓨터에 관한 맥락 정보도 함께 보고되므로, 발견 항목이 해당 이벤트를 발생시킨 장치와 사용자에 연결될 수 있습니다. 이 정보 중 일부는 개인 데이터입니다.

장치 식별자 — 컴퓨터의 호스트 이름과 하드웨어 일련 번호.
사용자 식별자 — AI 코딩 에이전트에 로그인한 사용자의 이메일 주소와 로컬 운영 체제 사용자 이름.
환경 세부 정보 — 운영 체제와 버전, AI 에이전트, 에이전트 버전과 사용 중인 모델, 에이전트의 MCP 구성 파일 내용, 활성화된 플러그인.

하드웨어 일련 번호는 로컬 임시 파일에 캐시되며, 명령을 실행한 사용자만 읽을 수 있습니다. 따라서 후크를 반복 실행해도 하드웨어 정보를 다시 조회하지 않습니다.

환경에서 이 데이터를 수집하는 것이 허용되지 않는다면 가드레일 후크를 설치하지 마세요(cycode ai-guardrails uninstall은 이미 설치된 후크를 제거합니다).

검사 명령

검사 실행

Cycode CLI 애플리케이션은 여러 유형의 검사를 제공하므로 상황에 가장 적합한 옵션을 선택할 수 있습니다. 현재 사용할 수 있는 옵션과 명령은 다음과 같습니다.

옵션	설명
`-t, --scan-type [secret\|iac\|sca\|sast]`	실행할 검사를 지정합니다(`secret`/`iac`/`sca`/`sast`). 기본값은 `secret`입니다.
`--show-secret BOOLEAN`	비밀 정보를 일반 텍스트로 표시합니다. 자세한 내용은 비밀 정보 표시/숨기기 섹션을 참조하세요.
`--soft-fail BOOLEAN`	실패해도 검사를 계속 실행하고 항상 오류가 아닌 상태 코드를 반환합니다. 자세한 내용은 소프트 실패 섹션을 참조하세요.
`--severity-threshold [INFO\|LOW\|MEDIUM\|HIGH\|CRITICAL]`	지정된 심각도 수준 이상인 위반 항목만 표시합니다.
`--sca-scan`	실행할 SCA 검사를 지정합니다(`package-vulnerabilities`/`license-compliance`/`unmaintained-packages`/`malicious-packages`). 기본값은 전체입니다.
`--monitor`	지정하면 검사 결과가 Cycode에 기록됩니다.
`--cycode-report`	콘솔 출력에 Cycode 플랫폼의 검사 보고서 링크를 표시합니다.
`--no-restore`	지정하면 Cycode가 복원 명령을 실행하지 않습니다. 직접 종속성만 검사합니다!
`--stop-on-error`	파일 수집 또는 종속성 복원에 실패하면 실패한 파일을 건너뛰고 계속하는 대신 검사를 중단합니다.
`--gradle-all-sub-projects`	모든 하위 프로젝트에 대해 gradle 복원 명령을 실행합니다. 이 명령은 다음 위치에서 실행해야 합니다.
`--maven-settings-file`	Maven 전용 옵션으로, 종속성을 검사할 때 사용자 지정 settings.xml 파일을 사용할 수 있습니다.
`--help`	지정된 명령의 옵션을 표시합니다.

명령	설명
commit-history	커밋 기록을 검사하거나 특정 커밋 간의 차이를 검사합니다.
path	명령에 지정된 경로의 파일을 검사합니다.
pre-commit	아직 커밋되지 않은 콘텐츠를 검사합니다. 플래그를 사용한 로컬 차이 검사도 지원합니다(IDE 친화적).
repository	기록을 포함하여 Git 저장소를 검사합니다.

옵션

심각도 옵션

검사 결과를 특정 심각도 기준으로 제한하려면 검사 명령에 --severity-threshold 인수를 추가할 수 있습니다.

예를 들어 다음 명령은 저장소에서 심각도가 Medium 이상인 정책 위반을 검사합니다.

cycode scan --severity-threshold MEDIUM repository ~/home/git/codebase

모니터 옵션

[!NOTE] 이 옵션은 SCA 검사에서만 사용할 수 있습니다.

SCA 유형 검사에서 발견된 SCA 정책과 연결된 검사 결과를 Cycode에 전송하려면 검사 명령에 --monitor 인수를 추가하세요.

예를 들어 다음 명령은 저장소에서 SCA 정책 위반을 검사하고 그 결과를 Cycode 플랫폼에 전송합니다.

cycode scan -t sca --monitor repository ~/home/git/codebase

Cycode 보고서 옵션

Cycode CLI를 사용해 검사를 수행할 때마다 보고서가 자동으로 생성되고 결과가 Cycode로 전송됩니다. 이 결과는 Cycode 플랫폼 내의 관련 정책(예: 저장소 검사에 대한 SCA 정책)과 연결됩니다.

검사가 완료된 후 CLI 출력에 Cycode 보고서의 직접 URL을 표시하려면 검사 명령에 --cycode-report 인수를 추가하세요.

cycode scan --cycode-report repository ~/home/git/codebase

CLI의 모든 검사 결과는 Cycode의 CLI 로그 섹션에 표시됩니다. 명령에 --cycode-report 플래그를 포함하면 검사 결과 다음에 특정 보고서로 연결되는 링크가 터미널에 표시됩니다.

[!WARNING] 이 페이지를 보려면 Cycode에서 owner 또는 admin 역할이 있어야 합니다.

cli-report

보고서 페이지는 다음과 같은 형태입니다.

패키지 취약점 옵션

[!NOTE] 이 옵션은 SCA 검사에서만 사용할 수 있습니다.

로컬 저장소의 특정 패키지 취약점을 검사하려면 -t sca 또는 --scan-type sca 옵션 뒤에 --sca-scan package-vulnerabilities 인수를 추가하세요.

앞의 예에서 패키지 취약점에 대해서만 SCA 검사를 실행하려면 다음 명령을 실행하면 됩니다.

cycode scan -t sca --sca-scan package-vulnerabilities repository ~/home/git/codebase

라이선스 준수 옵션

[!NOTE] 이 옵션은 SCA 검사에서만 사용할 수 있습니다.

로컬 저장소의 특정 브랜치를 검사하려면 --sca-scan license-compliance 인수 뒤에 검사할 브랜치 이름을 지정하세요.

앞의 예에서 dev이라는 브랜치만 검사하려면 다음 명령을 실행하면 됩니다.

cycode scan -t sca --sca-scan license-compliance repository ~/home/git/codebase -b dev

유지 관리가 중단된 패키지 옵션

[!NOTE] 이 옵션은 SCA 검사에서만 사용할 수 있습니다.

유지 관리가 중단된 패키지(OpenSSF Scorecard의 Maintained 검사가 낮은 패키지, 즉 최근 커밋이나 이슈 활동이 거의 없거나 전혀 없는 패키지)만 검사하려면 -t sca 또는 --scan-type sca 옵션 뒤에 --sca-scan unmaintained-packages 인수를 추가하세요.

[!NOTE] 유지 관리가 중단된 패키지를 보고할지는 조직의 정책에 따라 결정됩니다. 이 옵션은 검사에서 보고하는 항목의 범위를 좁힐 뿐이며, 테넌트에서 비활성화된 정책을 활성화할 수는 없습니다.

앞의 예에서 유지 관리가 중단된 패키지에 대해서만 SCA 검사를 실행하려면 다음 명령을 실행하면 됩니다.

cycode scan -t sca --sca-scan unmaintained-packages repository ~/home/git/codebase

악성 패키지 옵션

[!NOTE] 이 옵션은 SCA 검사에서만 사용할 수 있습니다.

취약한 패키지가 아니라 보안 권고에서 악성 코드로 식별한 종속성인 악성 패키지만 검사하려면 -t sca 또는 --scan-type sca 옵션 뒤에 --sca-scan malicious-packages 인수를 추가하세요.

악성 패키지 위반은 항상 Critical으로 보고되며, CVSS 점수와 수정 버전이 없습니다. 종속성을 제거하는 것만이 해결 방법입니다.

[!NOTE] 악성 패키지를 보고할지는 조직의 정책에 따라 결정됩니다. 이 옵션은 검사에서 보고하는 항목의 범위를 좁힐 뿐이며, 테넌트에서 비활성화된 정책을 활성화할 수는 없습니다.

앞의 예에서 악성 패키지에 대해서만 SCA 검사를 실행하려면 다음 명령을 실행하면 됩니다.

cycode scan -t sca --sca-scan malicious-packages repository ~/home/git/codebase

잠금 파일 복원 옵션

[!NOTE] 이 옵션은 SCA 검사에서만 사용할 수 있습니다.

SCA 검사를 실행하면 Cycode CLI는 지원되는 매니페스트 파일을 찾을 때마다 해당 파일의 종속성 잠금 파일을 자동으로 복원(생성)하려고 시도합니다. 이를 통해 매니페스트에 직접 나열된 종속성뿐 아니라 전이적 종속성도 검사할 수 있습니다. 이 단계를 건너뛰고 직접 종속성만 검사하려면 --no-restore 플래그를 사용하세요.

다음 에코시스템은 잠금 파일 자동 복원을 지원합니다.

에코시스템	매니페스트 파일	생성되는 잠금 파일	실행되는 도구(잠금 파일이 없는 경우)
npm	`package.json`	`package-lock.json`	`npm install --package-lock-only --ignore-scripts --no-audit`
Yarn	`package.json`	`yarn.lock`	`yarn install --ignore-scripts`
pnpm	`package.json`	`pnpm-lock.yaml`	`pnpm install --ignore-scripts`
Deno	`deno.json` / `deno.jsonc`	`deno.lock`	(기존 잠금 파일만 읽음)
Go	`go.mod`	`go.mod.graph`	`go list -m -json all` + `go mod graph`
Maven	`pom.xml`	`bcde.mvndeps`	`mvn dependency:tree`
Gradle	`build.gradle` / `build.gradle.kts`	`gradle-dependencies-generated.txt`	`gradle dependencies -q --console plain`
SBT	`build.sbt`	`build.sbt.lock`	`sbt dependencyLockWrite`
NuGet	`*.csproj`	`packages.lock.json`	`dotnet restore --use-lock-file`
Ruby	`Gemfile`	`Gemfile.lock`	`bundle --quiet`
Poetry	`pyproject.toml`	`poetry.lock`	`poetry lock`
pip	`pyproject.toml` / `requirements.txt`	`pylock.toml`	`pip lock .` / `pip lock -r requirements.txt -o pylock.toml`
Pipenv	`Pipfile`	`Pipfile.lock`	`pipenv lock`
PHP Composer	`composer.json`	`composer.lock`	`composer update --no-cache --no-install --no-scripts --ignore-platform-reqs`

매니페스트와 함께 잠금 파일이 이미 있으면 Cycode는 설치 명령을 실행하지 않고 해당 파일을 직접 읽습니다. SBT 사전 요구 사항: sbt-dependency-lock 플러그인을 설치해야 합니다. project/plugins.sbt에 다음 줄을 추가하세요.

addSbtPlugin("software.purpledragon" % "sbt-dependency-lock" % "1.5.1")

오류 발생 시 중단 옵션

기본적으로 Cycode는 파일을 읽을 수 없거나(예: 권한 오류로 인해) SCA 검사 중에 종속성 잠금 파일을 생성할 수 없는 경우에도 검사를 계속합니다. 실패한 항목은 경고와 함께 건너뛰고 나머지 파일에 대한 검사를 진행합니다.

--stop-on-error을 사용하면 이 동작을 변경할 수 있습니다. 이러한 오류가 처음 발생하면 검사를 즉시 중단하고 오류를 보고합니다.

cycode scan -t sca --stop-on-error path ~/home/git/codebase

이 옵션은 조용히 발생한 실패로 인해 불완전한 검사 결과가 생성될 수 있는 CI 파이프라인에서 유용합니다. --stop-on-error이 트리거되면 근본적인 문제를 해결하거나, SCA 복원 실패의 경우 --no-restore을 추가하여 잠금 파일 생성을 건너뛰고 직접 종속성만 검사할 수 있습니다.

--stop-on-error을 사용하면 CLI는 종료 코드를 통해 검사 오류와 정책 위반을 구분합니다.

종료 코드	의미
`0`	위반 사항 없이 검사 완료
`1`	검사가 완료되었으며 위반 사항이 발견됨
`2`	오류로 인해 검사 중단됨(`--stop-on-error`이 설정된 경우에만 해당)

저장소 검사

저장소 검사는 로컬 저장소 전체를 검사하여 노출된 비밀 정보나 안전하지 않은 구성 오류를 찾습니다. 이 포괄적인 검사 유형은 저장소의 현재 상태와 커밋 기록을 모두 살펴봅니다. 저장소에 현재 노출된 비밀 정보뿐 아니라 이전에 삭제된 비밀 정보도 찾습니다.

저장소 전체 검사를 실행하려면 다음을 실행하세요.

cycode scan repository {{path}}

예를 들어, ~/home/git/codebase에 저장된 저장소를 검사하려면 다음을 실행할 수 있습니다.

cycode scan repository ~/home/git/codebase

이 명령에서 사용할 수 있는 옵션은 다음과 같습니다.

옵션	설명
`-b, --branch TEXT`	설정하지 않으면 기본 브랜치를 검사합니다. 검사할 브랜치

브랜치 옵션

로컬 저장소의 특정 브랜치를 검사하려면 -b 인수(또는 --branch) 뒤에 검사할 브랜치 이름을 추가하세요.

앞의 예에서 dev이라는 브랜치만 검사하려면 다음을 실행할 수 있습니다.

cycode scan repository ~/home/git/codebase -b dev

경로 검사

경로 검사는 GIT 저장소에만 초점을 맞추는 대신 특정 로컬 디렉터리와 그 안의 모든 콘텐츠를 검사합니다.

디렉터리 검사를 실행하려면 다음을 실행하세요.

cycode scan path {{path}}

예를 들어, ~/home/git/codebase에 있는 디렉터리를 검사하려는 경우 다음을 실행할 수 있습니다.

cycode scan path ~/home/git/codebase

Terraform 계획 검사

Cycode CLI는 Terraform 계획 검사를 지원합니다(Terraform 0.12 이상 지원).

Terraform 계획 파일은 JSON 형식이어야 합니다(.json 확장자 사용).

구성 파일만 있는 경우 다음과 같이 계획을 생성할 수 있습니다.

Terraform 구성 파일이 포함된 작업 디렉터리를 초기화합니다.

terraform init
Terraform 실행 계획을 만들고 바이너리 출력을 저장합니다.

terraform plan -out={tfplan_output}
바이너리 출력 파일을 읽을 수 있는 JSON으로 변환합니다.

terraform show -json {tfplan_output} > {tfplan}.json
Cycode CLI로 {tfplan}.json을 검사합니다.

cycode scan -t iac path ~/PATH/TO/YOUR/{tfplan}.json

커밋 기록 검사

[!NOTE] IaC 검사에서는 커밋 기록 검사를 사용할 수 없습니다.

커밋 기록 검사 명령은 다음 두 가지 주요 기능을 제공합니다.

전체 기록 검사: 저장소 기록의 모든 커밋을 분석합니다.
차이 검사: 특정 커밋 간의 변경 사항만 검사합니다.

비밀 정보 검사는 저장소 기록의 모든 커밋을 분석할 수 있습니다. 비밀 정보가 추가된 후 삭제되었더라도 유출되거나 노출되었을 수 있기 때문입니다. SCA 및 SAST 검사의 경우 커밋 기록 명령은 커밋 간의 차이와 변경 사항을 검사하므로 풀 리퀘스트 검토와 점진적 검사에 적합합니다.

커밋 기록 검사는 Git 저장소의 커밋 기록을 살펴보며, 전체 기록 분석과 특정 변경 사항의 차이 검사를 모두 수행할 수 있습니다.

커밋 기록 검사를 실행하려면 다음을 실행하세요.

cycode scan commit-history {{path}}

예를 들어, ~/home/git/codebase에 저장된 저장소의 커밋 기록을 검사하려면 다음을 실행할 수 있습니다.

cycode scan commit-history ~/home/git/codebase

이 명령에서 사용할 수 있는 옵션은 다음과 같습니다.

옵션	설명
`-r, --commit-range TEXT`	이 git 저장소의 커밋 범위를 검사합니다. 기본적으로 cycode는 모든 커밋 기록을 검사합니다(예: HEAD~1).

커밋 범위 옵션(차이 검사)

커밋 범위 옵션을 사용하면 전체 저장소 기록 대신 특정 커밋 간의 변경 사항만 검사하는 차이 검사를 수행할 수 있습니다. 다음과 같은 경우에 특히 유용합니다.

풀 리퀘스트 검증: PR에서 도입된 변경 사항만 검사
점진적 CI/CD 검사: 전체 코드베이스 대신 최근 변경 사항에 집중
기능 브랜치 검토: main/master 브랜치와 변경 사항 비교
성능 최적화: 관련 변경 사항으로 범위를 제한하여 검사 속도 향상

커밋 범위 구문

--commit-range(-r) 옵션은 표준 Git 리비전 구문을 지원합니다.

구문	설명	예시
`commit1..commit2`	commit1부터 commit2까지의 변경 사항	`abc123..def456`
`commit1...commit2`	commit1에는 없고 commit2에 있는 변경 사항	`main...feature-branch`
`commit`	해당 커밋부터 HEAD까지의 변경 사항	`HEAD~1`
`branch1..branch2`	branch1부터 branch2까지의 변경 사항	`main..feature-branch`

차이 검사 예시

마지막 커밋의 변경 사항 검사:

cycode scan commit-history -r HEAD~1 ~/home/git/codebase

두 특정 커밋 간의 변경 사항 검사:

cycode scan commit-history -r abc123..def456 ~/home/git/codebase

main과 비교하여 기능 브랜치의 변경 사항 검사:

cycode scan commit-history -r main..HEAD ~/home/git/codebase

main과 기능 브랜치 간의 변경 사항 검사:

cycode scan commit-history -r main..feature-branch ~/home/git/codebase

최근 3개 커밋의 모든 변경 사항 검사:

cycode scan commit-history -r HEAD~3..HEAD ~/home/git/codebase

[!TIP] CI/CD 파이프라인에서는 ${{ github.event.pull_request.base.sha }}..${{ github.sha }}(GitHub Actions) 또는 $CI_MERGE_REQUEST_TARGET_BRANCH_SHA..$CI_COMMIT_SHA(GitLab CI)와 같은 환경 변수를 사용하여 PR/MR 변경 사항만 검사할 수 있습니다.

사전 커밋 검사

사전 커밋 검사는 저장소에 변경 사항을 커밋하기 전에 문제를 자동으로 식별합니다. 이 검사를 수동으로 실행할 필요는 없습니다. 이 가이드의 설치 섹션에 설명된 대로 사전 커밋 훅을 구성하세요.

사전 커밋 훅을 설치한 후에는 특정 커밋에서 검사를 건너뛰고 싶을 수 있습니다. 한 번의 커밋에서 검사를 건너뛰려면 git 명령에 다음을 추가하세요.

SKIP=cycode git commit -m <your commit message>`

이 명령에서 사용할 수 있는 옵션은 다음과 같습니다.

옵션	설명
`-b, --base-ref TEXT`	비교할 Git 참조(커밋, 브랜치 또는 태그). 기본값은 `HEAD`이며, 사전 커밋 훅의 동작과 일치합니다.
`--include-unstaged`	스테이징된 변경 사항뿐 아니라 추적 중인 파일의 스테이징되지 않은 변경 사항도 검사합니다. 기본적으로 꺼져 있습니다.
`--path PATH`	차이 검사의 범위를 제한할 선택적 경로입니다. 여러 번 지정할 수 있으며, 기본값은 전체 작업 디렉터리입니다.

로컬 차이 검사(IDE 통합)

--base-ref 및 --include-unstaged을 사용하면 pre-commit을 범용 로컬 차이 검사로 활용할 수 있습니다. 즉, 임의의 커밋(기본값 HEAD)과 현재 작업 디렉터리를 비교하며, 아직 스테이징되지 않은 편집 내용도 포함합니다. 이는 Git 훅 흐름 대신 작업 중 지속적으로 실시간 피드백을 제공해야 하는 IDE 플러그인 및 기타 도구를 위한 기능입니다. --include-unstaged와 함께 사용하면 --path을 통해 IDE에서 현재 편집기에서 열려 있는 파일만 검사하도록 범위를 지정할 수 있습니다.

[!NOTE] IaC 검사에서는 이러한 플래그를 통한 로컬 차이 검사를 사용할 수 없습니다.

마지막 커밋과 비교하여 현재 변경된 모든 항목(스테이징 및 스테이징되지 않은 항목) 검사:

cycode scan pre-commit --include-unstaged

특정 커밋 또는 브랜치와 비교하여 변경 사항 검사:

cycode scan pre-commit --include-unstaged --base-ref main

특정 파일만 검사(예: IDE에서 현재 열려 있는 파일):

cycode scan pre-commit --include-unstaged --path src/app.py

사전 푸시 검사

사전 푸시 검사는 원격 저장소에 변경 사항을 푸시하기 전에 문제를 자동으로 식별합니다. 이 훅은 클라이언트 측에서 실행되며 푸시할 커밋만 검사하므로, 문제가 원격 저장소에 도달하기 전에 효율적으로 찾아낼 수 있습니다.

[!NOTE] IaC 검사에서는 사전 푸시 훅을 사용할 수 없습니다.

사전 푸시 훅은 사전 커밋 프레임워크와 통합되며, 모든 git push 작업 전에 실행되도록 구성할 수 있습니다.

사전 푸시 훅 설치

사전 커밋 프레임워크를 사용하여 사전 푸시 훅을 설정하려면 다음을 수행하세요.

사전 커밋 프레임워크를 설치합니다(아직 설치하지 않은 경우).
```
pip3 install pre-commit
```

.pre-commit-config.yaml 파일을 만들거나 업데이트하여 사전 푸시 훅을 포함합니다.

repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.25.0
    hooks:
      - id: cycode-pre-push
        stages: [pre-push]

여러 검사 유형을 사용하려면 다음 구성을 사용합니다.

repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.25.0
    hooks:
      - id: cycode-pre-push          # Secrets scan
        stages: [pre-push]
      - id: cycode-sca-pre-push      # SCA scan
        stages: [pre-push]
      - id: cycode-sast-pre-push     # SAST scan
        stages: [pre-push]

사전 푸시 훅을 설치합니다.
```
pre-commit install --hook-type pre-push
```
설치가 성공하면 다음 메시지가 표시됩니다. Pre-push installed at .git/hooks/pre-push.
사전 푸시 훅을 최신 상태로 유지합니다.
```
pre-commit autoupdate
```

사전 푸시 검사의 작동 방식

훅은 푸시되는 각 커밋을 하나씩 검사하므로, 한 커밋에서 추가되고 이후 커밋에서 삭제된 비밀 정보도 찾아냅니다. 사전 커밋 프레임워크를 통해 설치한 경우 푸시 범위는 프레임워크에서 가져옵니다. 기존 브랜치에서는 원격 브랜치 이후의 새 커밋을, 새 브랜치에서는 아직 원격에 없는 커밋을 검사합니다(빈 원격 저장소에 푸시하는 경우 모든 커밋). 직접 작성한 .git/hooks/pre-push에서 실행하는 경우 범위는 git의 훅 입력에서 가져오며, 새 브랜치는 기본 브랜치와의 병합 기준 커밋부터 검사합니다(아래 참조).

태그, 브랜치 삭제, 최신 상태의 푸시처럼 검사할 항목이 없는 푸시는 검사 없이 통과합니다. 훅이 푸시 대상 항목을 확인할 수 없으면 조용히 통과하는 대신 실패하여 푸시를 차단합니다.

Cycode 사전 푸시 훅은 always_run: true 및 pass_filenames: false을 설정합니다. 검사는 파일 목록이 아니라 푸시되는 커밋을 대상으로 하기 때문입니다. always_run가 없으면 푸시된 커밋에서 변경된 파일이 없는 경우 사전 커밋 프레임워크가 훅을 건너뜁니다. 예를 들어 한 커밋에서 비밀 정보가 추가되고 다음 커밋에서 삭제된 경우가 이에 해당합니다. pass_filenames: false이 없으면 프레임워크는 검사에서 사용하지 않는 변경 파일 이름을 전달하며, 대규모 푸시에서는 파일을 여러 묶음으로 나누고 각 묶음마다 전체 검사를 실행합니다. 훅을 직접 정의하는 경우(예: repo: local 훅) 두 옵션을 모두 설정하세요.

기본 브랜치 자동 감지

직접 작성한 훅에서 실행할 때 사전 푸시 검사는 다음 우선순위에 따라 병합 기준 커밋 계산에 사용할 기본 브랜치를 감지합니다.

환경 변수: CYCODE_DEFAULT_BRANCH - 수동으로 재정의할 수 있습니다.
Git 원격 HEAD: git symbolic-ref refs/remotes/origin/HEAD을 사용하여 실제 원격 기본 브랜치를 감지합니다.
Git 원격 정보: symbolic-ref가 실패하면 git remote show origin을 사용합니다.
하드코딩된 대체값: 일반적인 기본 브랜치 이름(origin/main, origin/master, main, master)을 사용합니다.

사용자 지정 기본 브랜치 설정:

export CYCODE_DEFAULT_BRANCH=origin/develop

이 스마트 감지 기능은 저장소에서 main, master, develop 또는 다른 기본 브랜치 이름을 사용하는지와 관계없이 pre-push 훅이 올바르게 작동하도록 합니다.

Pre-Push 검사 건너뛰기

특정 푸시 작업에서 pre-push 검사를 건너뛰려면 다음을 사용하세요.

SKIP=cycode-pre-push git push

또는 모든 pre-push 훅을 건너뛰려면 다음을 사용하세요.

git push --no-verify

[!TIP] pre-push 훅은 git push 명령에서 트리거되며, 푸시할 예정인 커밋만 검사하므로 전체 저장소를 검사하는 것보다 효율적입니다.

검사에서 경로 제외

.cycodeignore 파일을 사용하여 검사에서 제외할 파일과 디렉터리를 Cycode CLI에 지정할 수 있습니다. 이 파일은 .gitignore 파일과 동일하게 작동합니다. 이를 통해 관련 코드에 검사 범위를 집중하고 특정 경로가 로컬에서 위반을 일으키지 않도록 할 수 있습니다.

작동 방식

작업 폴더에 .cycodeignore이라는 파일을 만듭니다.
.gitignore와 동일한 패턴을 사용하여 제외할 파일과 디렉터리를 나열합니다.
cycode scan 명령을 실행할 디렉터리에 이 파일을 둡니다.

[!WARNING]

잘못된 파일: .cycodeignore 파일에 구문 오류가 있으면 CLI 검사가 실패하고 오류를 반환합니다.

경로 무시와 위반 무시의 차이: 이 파일은 경로를 제외하는 용도입니다. 특정 위반을 무시하는 CLI 기능(예: --ignore-violation 플래그 사용)과는 다릅니다.

지원되는 스캐너

SAST
IaC (출시 예정)
SCA (출시 예정)

검사 결과

각 검사가 완료되면 문제가 발견되었는지 여부를 알리는 메시지가 표시됩니다.

문제가 발견되지 않으면 다음 성공 메시지와 함께 검사가 종료됩니다.

Good job! No issues were found!!! 👏👏👏

문제가 발견되면 대신 완료 시 위반 카드가 표시됩니다. 이 경우 결과 메시지에서 강조 표시된 특정 줄을 확인하려면 해당 파일을 검토해야 합니다. 문제를 해결하는 데 필요한 변경 사항을 적용한 다음 검사를 다시 실행하세요.

시크릿 표시/숨기기

아래 예시에서는 cli 하위 폴더에 있는 secret_test 파일에서 시크릿이 발견되었습니다. 메시지의 두 번째 부분에는 시크릿이 나타나는 특정 줄이 표시되며, 이 경우 googleApiKey에 할당된 값입니다.

예시에서는 실제 시크릿 값을 별표로 대부분 대체하여 가린 점에 유의하세요. 검사는 기본적으로 시크릿을 가리지만, 원하는 경우 이 기능을 비활성화하여 전체 시크릿을 확인할 수 있습니다(검사 결과를 보는 컴퓨터가 다른 사람의 엿보기로부터 충분히 안전하다고 가정).

시크릿 가리기를 비활성화하려면 모든 유형의 검사에 --show-secret 인수를 추가하세요.

다음 예시에서는 전체 시크릿을 표시하는 옵션을 활성화한 상태로 cli 하위 디렉터리를 대상으로 Path Scan을 실행합니다.

cycode scan --show-secret path ./cli

그러면 결과가 가려지지 않은 상태로 표시됩니다.

소프트 실패

일반적인 작동 방식에서 CLI는 검사 결과에 문제가 발견되면 종료 코드 1를 반환합니다. CI/CD 설정에 따라 대개 전체 작업이 실패하게 됩니다. 이를 원하지 않는다면 소프트 실패 기능을 사용할 수 있습니다.

모든 유형의 검사에 --soft-fail 옵션을 추가하면 결과 발견 여부와 관계없이 종료 코드가 0으로 강제 설정됩니다.

검사 결과 예시

Secrets 결과 예시

╭─────────────────────────────────────────────────────────────── Hardcoded generic-password is used ───────────────────────────────────────────────────────────────╮
│                                                                                                                                               Violation 12 of 12 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │  Severity    🟠 MEDIUM                             │ │   34 };                                                                                               │ │
│ │  In file     /Users/cycodemacuser/NodeGoat/test/s  │ │   35                                                                                                  │ │
│ │              ecurity/profile-test.js               │ │   36 var sutUserName = "user1";                                                                       │ │
│ │  Secret SHA  b4ea3116d868b7c982ee6812cce61727856b  │ │ ❱ 37 var sutUserPassword = "Us*****23";                                                               │ │
│ │              802b3063cd5aebe7d796988552e0          │ │   38                                                                                                  │ │
│ │  Rule ID     68b6a876-4890-4e62-9531-0e687223579f  │ │   39 chrome.setDefaultService(service);                                                               │ │
│ ╰────────────────────────────────────────────────────╯ │   40                                                                                                  │ │
│                                                        ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ A generic secret or password is an authentication token used to access a computer or application and is assigned to a password variable.                     │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

IaC 결과 예시

╭──────────── Enable Content Encoding through the attribute 'MinimumCompressionSize'. This value should be greater than -1 and smaller than 10485760. ─────────────╮
│                                                                                                                                              Violation 45 of 110 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │  Severity      🟠 MEDIUM                           │ │   20 BinaryMediaTypes:                                                                                │ │
│ │  In file       ...ads-copy/iac/cft/api-gateway/ap  │ │   21   - !Ref binaryMediaType1                                                                        │ │
│ │                i-gateway-rest-api/deploy.yml       │ │   22   - !Ref binaryMediaType2                                                                        │ │
│ │  IaC Provider  CloudFormation                      │ │ ❱ 23 MinimumCompressionSize: -1                                                                       │ │
│ │  Rule ID       33c4b90c-3270-4337-a075-d3109c141b  │ │   24 EndpointConfiguration:                                                                           │ │
│ │                53                                  │ │   25   Types:                                                                                         │ │
│ ╰────────────────────────────────────────────────────╯ │   26     - EDGE                                                                                       │ │
│                                                        ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ This policy validates the proper configuration of content encoding in AWS API Gateway. Specifically, the policy checks for the attribute                     │ │
│ │ 'minimum_compression_size' in API Gateway REST APIs. Correct configuration of this attribute is important for enabling content encoding of API responses for │ │
│ │ improved API performance and reduced payload sizes.                                                                                                          │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

SCA 결과 예시

╭─────────────────────────────────────────────────────── [CVE-2019-10795] Prototype Pollution in undefsafe ────────────────────────────────────────────────────────╮
│                                                                                                                                             Violation 172 of 195 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │  Severity               🟠 MEDIUM                  │ │   26758   "integrity": "sha1-5z3T17DXxe2G+6xrCufYxqadUPo=",                                           │ │
│ │  In file                /Users/cycodemacuser/Node  │ │   26759   "dev": true                                                                                 │ │
│ │                         Goat/package-lock.json     │ │   26760 },                                                                                            │ │
│ │  CVEs                   CVE-2019-10795             │ │ ❱ 26761 "undefsafe": {                                                                                │ │
│ │  Package                undefsafe                  │ │   26762   "version": "2.0.2",                                                                         │ │
│ │  Version                2.0.2                      │ │   26763   "resolved": "https://registry.npmjs.org/undefsafe/-/undefsafe-2.0.2.tgz",                   │ │
│ │  First patched version  Not fixed                  │ │   26764   "integrity": "sha1-Il9rngM3Zj4Njnz9aG/Cg2zKznY=",                                           │ │
│ │  Dependency path        nodemon 1.19.1 ->          │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ │                         undefsafe 2.0.2            │                                                                                                           │
│ │  Rule ID                9c6a8911-e071-4616-86db-4  │                                                                                                           │
│ │                         943f2e1df81                │                                                                                                           │
│ ╰────────────────────────────────────────────────────╯                                                                                                           │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ undefsafe before 2.0.3 is vulnerable to Prototype Pollution. The 'a' function could be tricked into adding or modifying properties of Object.prototype using │ │
│ │ a __proto__ payload.                                                                                                                                         │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

SAST 결과 예시

╭───────────────────────────────────────────── [CWE-208: Observable Timing Discrepancy] Observable Timing Discrepancy ─────────────────────────────────────────────╮
│                                                                                                                                               Violation 24 of 49 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │  Severity       🟠 MEDIUM                          │ │   173         " including numbers, lowercase and uppercase letters.";                                 │ │
│ │  In file        /Users/cycodemacuser/NodeGoat/app  │ │   174     return false;                                                                               │ │
│ │                 /routes/session.js                 │ │   175 }                                                                                               │ │
│ │  CWE            CWE-208                            │ │ ❱ 176 if (password !== verify) {                                                                      │ │
│ │  Subcategory    Security                           │ │   177     errors.verifyError = "Password must match";                                                 │ │
│ │  Language       js                                 │ │   178     return false;                                                                               │ │
│ │  Security Tool  Bearer (Powered by Cycode)         │ │   179 }                                                                                               │ │
│ │  Rule ID        19fbca07-a8e7-4fa6-92ac-a36d15509  │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ │                 fa9                                │                                                                                                           │
│ ╰────────────────────────────────────────────────────╯                                                                                                           │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Observable Timing Discrepancy occurs when the time it takes for certain operations to complete can be measured and observed by attackers. This vulnerability │ │
│ │ is particularly concerning when operations involve sensitive information, such as password checks or secret comparisons. If attackers can analyze how long   │ │
│ │ these operations take, they might be able to deduce confidential details, putting your data at risk.                                                         │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

회사 맞춤형 수정 지침

회사에서 Cycode 포털의 관련 정책에 맞춤형 수정 지침을 설정한 경우, 추가한 수정 지침이 포함된 “회사 지침” 필드가 표시됩니다. 회사 지침을 추가하지 않았다면 이 필드는 CLI 도구에 표시되지 않습니다.

검사 결과 무시

무시 규칙을 추가하여 특정 시크릿 값, 특정 SHA512 값, 특정 경로, 특정 Cycode 시크릿 및 IaC 규칙 ID를 무시할 수 있습니다. 이렇게 하면 검사에서 해당 값에 대한 알림이 표시되지 않습니다. 무시 규칙은 ./.cycode/config.yaml 파일에 로컬로 작성 및 저장됩니다.

[!WARNING] 검사에서 실제 양성 결과를 포착할 수 있도록 무시할 값, 경로 및 정책을 신중하게 고려한 후 값을 추가해야 합니다.

다음은 cycode ignore 명령에서 사용할 수 있는 옵션입니다.

옵션	설명
`--by-value TEXT`	시크릿 검사 중 특정 값을 무시합니다. 자세한 내용은 시크릿 값 무시를 참조하세요.
`--by-sha TEXT`	시크릿 검사 중 문자열의 특정 SHA512 표현을 무시합니다. 자세한 내용은 시크릿 SHA 값 무시를 참조하세요.
`--by-path TEXT`	특정 경로를 검사하지 않습니다. 검사 유형을 지정해야 합니다. 자세한 내용은 경로 무시를 참조하세요.
`--by-rule TEXT`	특정 시크릿 규칙 ID/IaC 규칙 ID/SCA 규칙 ID 검사를 무시합니다. 자세한 내용은 시크릿 또는 IaC 규칙 무시를 참조하세요.
`--by-package TEXT`	SCA 검사 중 특정 패키지 버전 검사를 무시합니다. 예상 패턴 - `name@version`. 자세한 내용은 패키지 무시를 참조하세요.
`--by-cve TEXT`	SCA 검사 중 특정 CVE 검사를 무시합니다. 예상 패턴: CVE-YYYY-NNN.
`-t, --scan-type [secret\|iac\|sca\|sast]`	실행할 검사를 지정합니다(`secret`/`iac`/`sca`/`sast`). 기본값은 `secret`입니다.
`-g, --global`	무시 규칙을 추가하고 전역 `.cycode` 구성 파일에서 업데이트합니다.

시크릿 값 무시

특정 시크릿 값을 무시하려면 --by-value 플래그를 사용해야 합니다. 이 플래그를 사용하면 지정한 시크릿 값이 이후의 모든 검사에서 무시됩니다. 다음 명령을 사용하여 무시할 시크릿 값을 추가하세요.

cycode ignore --by-value {{secret-value}}

이 섹션 상단의 예시에서 특정 시크릿 값을 무시하는 명령은 다음과 같습니다.

cycode ignore --by-value h3110w0r1d!@#$350

위 예시에서 h3110w0r1d!@#$350 값을 마스킹되지 않은 시크릿 값으로 바꾸세요. 검사 결과에서 시크릿 값을 확인하는 방법은 Cycode 검사 옵션을 참조하세요.

시크릿 SHA 값 무시

특정 시크릿 SHA 값을 무시하려면 --by-sha 플래그를 사용해야 합니다. 이 플래그를 사용하면 지정한 시크릿 SHA 값이 이후의 모든 검사에서 무시됩니다. 다음 명령을 사용하여 무시할 시크릿 SHA 값을 추가하세요.

cycode ignore --by-sha {{secret-sha-value}}

이 섹션 상단의 예시에서 특정 시크릿 SHA 값을 무시하는 명령은 다음과 같습니다.

cycode ignore --by-sha a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0

위 예시에서 a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0 값을 시크릿 SHA 값으로 바꾸세요.

경로 무시

시크릿, IaC 또는 SCA 검사에서 특정 경로를 무시하려면 -t, --scan-type 플래그와 함께 --by-path 플래그를 사용해야 합니다(검사 유형을 지정해야 함). 이렇게 하면 지정한 검사 유형의 이후 모든 검사에서 해당 경로가 무시됩니다. 다음 명령을 사용하여 무시할 경로를 추가하세요.

cycode ignore -t {{scan-type}} --by-path {{path}}

이 섹션 상단의 예시에서 시크릿 검사에서 특정 경로를 무시하는 명령은 다음과 같습니다.

cycode ignore -t secret --by-path ~/home/my-repo/config

위 예시에서 ~/home/my-repo/config 값을 경로 값으로 바꾸세요.

이 섹션 상단의 예시에서 IaC 검사에서 특정 경로를 무시하는 명령은 다음과 같습니다.

cycode ignore -t iac --by-path ~/home/my-repo/config

위 예시에서 ~/home/my-repo/config 값을 경로 값으로 바꾸세요.

이 섹션 상단의 예시에서 SCA 검사에서 특정 경로를 무시하는 명령은 다음과 같습니다.

cycode ignore -t sca --by-path ~/home/my-repo/config

위 예시에서 ~/home/my-repo/config 값을 경로 값으로 바꾸세요.

시크릿, IaC, SCA 또는 SAST 규칙 무시

특정 시크릿, IaC, SCA 또는 SAST 규칙을 무시하려면 -t, --scan-type 플래그와 함께 --by-rule 플래그를 사용해야 합니다(검사 유형을 지정해야 함). 이렇게 하면 지정한 규칙 ID 값이 이후의 모든 검사에서 무시됩니다. 다음 명령을 사용하여 무시할 규칙 ID 값을 추가하세요.

cycode ignore -t {{scan-type}} --by-rule {{rule-ID}}

이 섹션 상단의 예시에서 특정 시크릿 규칙 ID를 무시하는 명령은 다음과 같습니다.

cycode ignore -t secret --by-rule ce3a4de0-9dfc-448b-a004-c538cf8b4710

위 예시에서 ce3a4de0-9dfc-448b-a004-c538cf8b4710 값을 무시할 규칙 ID로 바꾸세요.

이 섹션 상단의 예시에서 특정 IaC 규칙 ID를 무시하는 명령은 다음과 같습니다.

cycode ignore -t iac --by-rule bdaa88e2-5e7c-46ff-ac2a-29721418c59c

위 예시에서 bdaa88e2-5e7c-46ff-ac2a-29721418c59c 값을 무시할 규칙 ID로 바꾸세요.

이 섹션 상단의 예시에서 특정 SCA 규칙 ID를 무시하는 명령은 다음과 같습니다.

cycode ignore -t sca --by-rule dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b

위 예시에서 dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b 값을 무시할 규칙 ID로 바꾸세요.

패키지 무시

[!NOTE] 이 옵션은 SCA 검사에서만 사용할 수 있습니다.

SCA 검사에서 특정 패키지를 무시하려면 -t, --scan-type 플래그와 함께 --by-package 플래그를 사용해야 합니다(sca 검사 유형을 지정해야 함). 이렇게 하면 {{package_name}}@{{package_version}} 형식을 사용하여 지정한 패키지가 이후의 모든 검사에서 무시됩니다. 다음 명령을 사용하여 무시할 패키지와 버전을 추가하세요.

cycode ignore --scan-type sca --by-package {{package_name}}@{{package_version}}

또는

cycode ignore -t sca --by-package {{package_name}}@{{package_version}}

아래 예시에서 특정 SCA 패키지를 무시하는 명령은 다음과 같습니다.

cycode ignore --scan-type sca --by-package pyyaml@5.3.1

위 예시에서 pyyaml을 패키지 이름으로, 5.3.1을 무시할 패키지 버전으로 바꾸세요.

구성 파일을 통한 무시

적용된 무시 규칙은 config.yaml이라는 구성 파일에 저장됩니다. 이 파일은 개발자 간에 쉽게 공유하거나 원격 Git에 커밋할 수도 있습니다. 이 파일은 항상 .cycode 폴더에 있습니다. 폴더 이름은 점(.)으로 시작하므로 폴더를 보려면 숨김 파일 표시를 활성화해야 합니다.

구성 파일 경로

기본적으로 모든 cycode ignore 명령은 CLI를 실행한 현재 디렉터리에 무시 규칙을 저장합니다.

예: /Users/name/projects/backend에서 무시 CLI 명령을 실행하면 /Users/name/projects/backend/.cycode에 config.yaml이 생성됩니다.

➜  backend  pwd
/Users/name/projects/backend
➜  backend  cycode ignore --by-value test-value
➜  backend  tree -a
.
└── .cycode
    └── config.yaml

2 directories, 1 file

두 번째 방법은 무시 규칙을 전역 구성 파일에 저장하는 것입니다. 전역 구성 파일의 경로는 ~/.cycode/config.yaml입니다. 여기서 ~은 macOS에서 users home directory, for example, /Users/name`을 의미합니다.

cycode ignore 명령의 -g 플래그를 사용하면 전역 공간에 저장할 수 있습니다. 예: cycode ignore -g --by-value test-value.

올바른 작업 디렉터리

.cycode 폴더를 올바른 위치에 두고 같은 위치에서 CLI를 실행하는 것이 매우 중요합니다. CI/CD(GitHub Actions, Jenkins 등)와 같은 다양한 환경에서 작업할 때는 이를 다시 확인해야 합니다.

.cycode 폴더를 저장소 루트에 커밋할 수 있습니다. 이 경우 저장소 루트에서 CLI 검사를 실행해야 합니다. 요구 사항에 맞지 않는다면 .cycode 폴더를 원하는 위치에 임시로 복사한 다음 해당 폴더에서 CLI 검사를 실행할 수 있습니다.

config의 무시 규칙 구조

CLI가 무시 규칙을 저장하는 방식을 이해하면 이러한 구성 파일을 읽거나 CLI 없이 수정할 수 있습니다.

추상 YAML 구조:

exclusions:
  {scanTypeName}:
    {ignoringType}:
    - someIgnoringValue1
    - someIgnoringValue2

scanTypeName의 가능한 값: iac, sca, sast, secret.

ignoringType의 가능한 값: paths, values, rules, packages, shas, cves.

[!WARNING] "값으로 무시"의 값은 일반 텍스트로 저장되지 않습니다! CLI는 값의 sha256 해시를 저장합니다. 구성 파일을 직접 수정할 때는 문자열의 해시를 입력해야 합니다.

실제 config.yaml의 예:

exclusions:
  iac:
    rules:
    - bdaa88e2-5e7c-46ff-ac2a-29721418c59c
  sca:
    packages:
    - pyyaml@5.3.1
  secret:
    paths:
    - /Users/name/projects/build
    rules:
    - ce3a4de0-9dfc-448b-a004-c538cf8b4710
    shas:
    - a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
    values:
    - a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
    - 60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752

Report 명령

SBOM 보고서 생성

소프트웨어 자재 명세서(SBOM)는 애플리케이션의 개발 및 제공에 사용되는 모든 구성 요소와 소프트웨어 종속 항목의 목록입니다. 이 명령을 사용하면 로컬 프로젝트 또는 저장소 URI의 SBOM 보고서를 생성할 수 있습니다.

이 명령에서 사용할 수 있는 옵션은 다음과 같습니다.

옵션	설명	필수	기본값
`-f, --format [spdx-2.2\|spdx-2.3\|cyclonedx-1.4]`	SBOM 형식	예
`-o, --output-format [JSON]`	출력 파일 형식 지정	아니요	json
`--output-file PATH`	출력 파일	아니요	현재 디렉터리에 저장되는 자동 생성 파일 이름
`--include-vulnerabilities`	취약점 포함	아니요	False
`--include-dev-dependencies`	개발 종속 항목 포함	아니요	False

이 명령에서 사용할 수 있는 명령은 다음과 같습니다.

명령	설명
`path`	명령에 지정된 경로의 SBOM 보고서 생성
`repository-url`	명령에 지정된 저장소 URI의 SBOM 보고서 생성

저장소

저장소 URI의 SBOM 보고서를 생성하려면:
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> repository_url <repository url>

예:
cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies repository_url https://github.com/cycodehq/cycode-cli.git

로컬 프로젝트

경로의 SBOM 보고서를 생성하려면:
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> path </path/to/project>

예:
cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies path /path/to/local/project

path 하위 명령은 다음 추가 옵션을 지원합니다.

옵션	설명
`--no-restore`	잠금 파일 복원을 건너뛰고 직접 종속 항목만 검사합니다. 자세한 내용은 Lock Restore Option을 참조하세요.
`--gradle-all-sub-projects`	모든 하위 프로젝트에 대해 Gradle 복원 명령을 실행합니다(다중 프로젝트 Gradle 빌드의 루트에서 사용).
`--maven-settings-file`	Maven 전용 옵션으로, 종속 항목 트리를 빌드할 때 사용자 지정 settings.xml 파일을 사용할 수 있습니다.

Import 명령

SBOM 가져오기

소프트웨어 자재 명세서(SBOM)는 애플리케이션의 개발 및 제공에 사용되는 모든 구성 요소와 소프트웨어 종속 항목의 목록입니다. 이 명령을 사용하면 파일 시스템의 SBOM 파일을 Cycode로 가져올 수 있습니다.

이 명령에서 사용할 수 있는 옵션은 다음과 같습니다.

옵션	설명	필수	기본값
`-n, --name TEXT`	SBOM 표시 이름	예
`-v, --vendor TEXT`	SBOM을 제공한 엔터티의 이름	예
`-l, --label TEXT`	SBOM에 레이블 연결	아니요
`-o, --owner TEXT`	이 SBOM의 연락 담당자인 Cycode 사용자의 이메일 주소	아니요
`-b, --business-impact [High \| Medium \| Low]`	비즈니스 영향	아니요	Medium

예:
cycode import sbom --name example-sbom --vendor cycode -label tag1 -label tag2 --owner example@cycode.com /path/to/local/project

스캔 로그

모든 CLI 스캔은 Cycode에 기록됩니다. 로그는 Settings > CLI Logs에서 확인할 수 있습니다.

구문 도움말

언제든지 모든 명령에 --help 인수를 추가하면 사용 가능한 옵션과 구문을 표시하는 도움말 메시지를 볼 수 있습니다.

일반 도움말을 보려면 다음 명령을 입력하세요.

cycode --help

스캔 옵션을 보려면 다음을 입력하세요.

cycode scan --help

특정 유형의 스캔에 사용할 수 있는 옵션을 보려면 다음을 입력하세요.

cycode scan {{option}} --help

예를 들어, 경로 스캔에 사용할 수 있는 옵션을 보려면 다음을 입력하세요.

cycode scan path --help

무시 스캔 기능에 사용할 수 있는 옵션을 보려면 다음 명령을 사용하세요.

cycode ignore --help

보고서에 사용할 수 있는 옵션을 보려면 다음 명령을 사용하세요.

cycode report --help

특정 유형의 보고서에 사용할 수 있는 옵션을 보려면 다음을 입력하세요.

cycode scan {{option}} --help

Cycode

Cycode MCP(으)로 무엇을 할 수 있나요?

문서

Cycode CLI 사용자 가이드

목차

사전 요구 사항

설치

Cycode CLI 설치

Auth 명령 사용

Configure 명령 사용

환경 변수에 추가

Unix/Linux에서:

Windows에서

Pre-Commit Hook 설치

Pre-Commit Hook 설치

Pre-Push Hook 설치

Cycode CLI 명령

인증서 및 프록시

MCP 명령 [EXPERIMENT]

MCP 서버 시작

사용 가능한 옵션

MCP 도구

사용 예시

기본 명령 예시

구성 예시

Cursor/VS Code/Claude Desktop 등에서 MCP 사용(mcp.json)

MCP 서버를 백그라운드에서 실행

고급 구성

시간 제한 및 사용자 지정 인증서(프록시 환경)

하위 에이전트용 도구 사전 승인(Claude Code)

MCP 문제 해결

MCP 구성

Platform 명령 [BETA]

명령 검색

플랫폼 예시

플랫폼 참고 사항 및 제한 사항

AI 가드레일 [BETA]

AI 가드레일에서 수집하는 데이터

검사 명령

검사 실행

옵션

심각도 옵션

모니터 옵션

Cycode 보고서 옵션

패키지 취약점 옵션

라이선스 준수 옵션

유지 관리가 중단된 패키지 옵션

악성 패키지 옵션

잠금 파일 복원 옵션

오류 발생 시 중단 옵션

저장소 검사

브랜치 옵션

경로 검사

Terraform 계획 검사

커밋 기록 검사

커밋 범위 옵션(차이 검사)

커밋 범위 구문

차이 검사 예시

사전 커밋 검사

로컬 차이 검사(IDE 통합)

사전 푸시 검사

사전 푸시 훅 설치

사전 푸시 검사의 작동 방식

기본 브랜치 자동 감지

Pre-Push 검사 건너뛰기

검사에서 경로 제외

작동 방식

지원되는 스캐너

검사 결과

시크릿 표시/숨기기

소프트 실패

검사 결과 예시

Secrets 결과 예시

IaC 결과 예시

SCA 결과 예시

SAST 결과 예시

회사 맞춤형 수정 지침

검사 결과 무시

시크릿 값 무시

시크릿 SHA 값 무시