버전: 2508.1

Sparrow On-Demand 시작 가이드

빠른 시작

가이드에서는 Sparrow On-Demand에 연결한 다음, 분석을 수행하고, 결과를 확인하며, 사용량을 확인하는 등 제품을 사용하는 방법을 알아보겠습니다.

🙍‍♂️ 계정 등록

계정을 만들려면 스패로우 홈페이지의 문의하기로 이동하세요.
솔루션/제품/서비스 문의에 문의를 남겨주세요. 스패로우에서 해당 고객에게 계정을 발급해 드립니다.
자세한 내용은 계정 등록을 확인하세요.

🔑 토큰 발급

위에서 발급한 계정으로 Sparrow On-Demand에 로그인하고, 오른쪽 위에 있는 내 계정에서 개인 또는 조직용 API 키를 생성하세요.
생성된 API 키는 API 헤더 혹은 SDK의 파라미터에 입력합니다.
자세한 내용은 토큰 발급을 확인하세요.

⚙️ 환경 구성

분석 요청을 전송하기 위해 API 호출 환경을 구성하세요.
사용자가 분석할 프로젝트의 소스코드, 저장소 혹은 URL 등 분석 대상을 준비하세요.

🎯 분석 실행 및 결과 다운로드

분석 요청 API를 전송하거나 Java SDK 혹은 Node.js SDK를 실행하여 분석을 수행합니다.
분석을 요청하면 분석 콜백을 통해 분석이 어떤 상태인지 확인할 수 있습니다. 분석 결과는 분석 결과 다운로드 API를 전송하세요.
자세한 내용은 분석 요청과 콜백을 확인하세요.

📃 분석 결과 살펴보기

분석 결과에는 소스코드, 저장소 혹은 URL에서 검출한 이슈가 포함됩니다. 다운로드한 결과 파일에 대한 자세한 내용은 분석 결과 파일을 참고하세요.
분석이 실패한 경우 원인을 결과 코드로 표시합니다. 자세한 내용은 결과 코드 모음을 참고하세요.

사용 가이드

계정 등록

Sparrow On-Demand에서 제공하는 API 혹은 SDK를 사용하기 위해서는 API 키를 발급해야 합니다. 또한, API 키를 발급하기 위해 사용자 계정이 필요합니다. 다음과 같은 방법으로 계정을 등록하실 수 있습니다.

스패로우 홈페이지의 문의하기로 이동하세요.
문의자 정보를 입력하세요.
구분에서 솔루션/제품/서비스 문의를 선택하고, 항목에서 On-Demand를 선택하세요.
제목을 입력하시고 내용에 Sparrow On-Demand를 사용해보고 싶다는 문의를 남겨주세요.
스패로우에서 해당 고객에게 계정을 전달합니다.

이제 등록된 계정으로 API 키를 발급하세요.

정보

(주)스패로우와 Sparrow On-Demand 솔루션 파트너십 계약을 체결하신 고객만 정식으로 Sparrow On-Demand 서비스를 사용하실 수 있습니다. 파트너십을 보유하신 고객에게는 파트너십 계약을 완료하는 시점에 계정 ID와 비밀번호가 발급됩니다.

토큰 발급

Sparrow On-Demand 솔루션을 사용하려면 API 키가 필요합니다. API 키는 네트워크를 통해 API 혹은 SDK를 호출하는 사용자가 인증된 고객인지를 확인하는 수단입니다. 서비스를 사용하기 위해 요청을 전송할 때 개별 요청마다 API 키를 포함해야 합니다. 이렇게 발급된 API 키를 사용해서 수행한 분석은 모두 해당 고객께서 사용하신 서비스로 구분합니다.

Sparrow On-Demand에서는 API 키로 사용할 토큰을 발급 받으실 수 있습니다. 자세한 방법은 다음을 참고하세요.

Sparrow On-Demand 홈에서 미리 등록된 계정 ID와 비밀번호를 입력하고 로그인하세요.
오른쪽 위에 있는 사용자 이름 > 내 계정을 클릭하세요.

토큰 관리에서 토큰 추가 버튼을 클릭하세요.
만료 시간과 설명을 입력하고 추가하기 버튼을 클릭하세요.
토큰이 발급됩니다.

발급된 토큰은 API를 호출할 때 헤더의 Token Bearer에 추가하거나 SDK 클라이언트를 생성할 때 인자로 입력해야 합니다.

분석 요청과 콜백

사용자는 콜백을 통해 요청의 분석에 대한 정보를 수신할 수 있습니다.

정보

수신할 콜백 유형 및 콜백할 서버는 분석을 요청할 때 지정하세요.

분석 요청 과정

콜백 유형

콜백 유형에는 두 가지가 있습니다.

ANALYSIS_PROGRESS분석 상태 콜백

분석 상태가 변경되거나 분석 정보가 업데이트되면 분석 상태를 콜백으로 전송합니다.

ANALYSIS_COMPLETE분석 종료 콜백

모든 과정이 종료되면 종료 콜백을 보냅니다. 분석이 성공, 실패, 중지되는 경우입니다.

콜백 서버

콜백 서버도 콜백에 따라 두 가지를 지정할 수 있습니다.

urlstring

상태 콜백 서버: 분석 상태 콜백을 수신할 사용자의 서버입니다.
종료 콜백 서버: 분석 종료 콜백을 수신할 사용자의 서버입니다.

정보

두 가지 콜백을 동일한 서버에서 수신하도록 두 콜백에 같은 URL을 설정할 수도 있습니다.

분석 결과 파일

분석이 종료되면 분석 결과 요청 API를 전송하여 분석 결과를 파일로 다운로드할 수 있습니다.

정보

여기를 클릭하면 샘플 결과 파일을 다운로드할 수 있습니다.

result.zip/
    /summary.json
    /asset
    /sbom
        SPDX.spdx
        CycloneDX.json
        SWID.zip
        ...
    /licenseNotice
        HTML.html
        MARKDOWN.md
        TXT.txt
    /issue
        1.json
        2.json
        ...
    /workMessage.json

다운로드된 파일은 result.zip 형태로 압축되어 있습니다. 자세한 내용은 여기를 참고하세요.

summary.json: 분석에 대한 요약 정보가 있는 파일입니다. 분석 결과, 취약점 수, 분석 시간 정보 등이 포함됩니다.
asset: 분석에서 식별한 개별 분석 대상을 자산이라고 합니다. 이 파일에는 자산에 대한 정보가 포함되어 있습니다.
- 소스코드 및 오픈소스 분석: 분석 대상인 파일의 목록
- 웹취약점 분석: 수집된 URL의 목록
issue: 분석에서 검출된 이슈에 대한 정보를 모아둔 폴더입니다. 폴더 안에 이슈 정보를 모아둔 다수의 json 파일이 포함되어 있습니다. 분석에 따라 제공하는 이슈 정보에 차이가 있다는 점에 유의하세요.
- 소스코드 분석: 이슈 검출 규칙의 이름, 파일, 라인 등
- 오픈소스 분석: 이슈 검출 규칙의 이름, 오픈소스의 이름, 라이선스 정보 등
- 웹취약점 분석: 이슈 검출 규칙의 이름, 분석 대상 URL, 파라미터를 비롯한 요청 정보 등
workMessage.json: 분석과 관련되어 확인해야 할 주의 사항이나 경고를 기록한 작업 메세지를 모아둔 파일입니다.
licenseNotice: 라이선스 고지문을 모아둔 폴더입니다. 폴더 안에 텍스트(.txt), 마크다운(.md) 및 HTML(.html) 형식의 파일이 포함되어 있습니다. 자세한 내용은 라이선스 고지문을 참고하세요.
sbom: SBOM 파일을 모아둔 폴더입니다. 형식 및 버전에 따라 다수의 SBOM 파일이 포함되어 있습니다. 자세한 내용은 SBOM을 참고하세요.

정보

licenseNotice 및 sbom 폴더는 오픈소스 분석의 결과를 다운로드한 경우에만 포함됩니다.

라이선스 고지문

Sparrow On-Demand는 오픈소스, 상용 소프트웨어, 내부에서 사용하는 라이브러리 등을 확인하여 사용자의 편의를 위해 라이선스 고지문을 자동으로 생성합니다. 하지만 정확한 정보를 위해서는 반드시 라이선스 전문을 확인해야 합니다. 라이선스 고지문에는 엄격한 표준 형식이 없지만, 관행적으로 널리 사용되는 구성과 패턴이 존재합니다. Sparrow On-Demand 고지문에도 다음과 같은 내용이 표시됩니다.

컴포넌트 이름
SPDX ID
라이선스 전문
저작권 정보
출처 URL
컴포넌트 버전

SBOM

SBOM은 소프트웨어 자재 명세서(Software Bill of Materials)의 약자이며 소프트웨어 제품의 구성 요소와 의존성을 기록한 목록입니다. SBOM은 목적에 따라 필요한 정보를 담은 여러가지 형식으로 제공됩니다. Sparrow On-Demand에서는 다음과 같은 대표적인 SBOM 형식을 지원하고 있습니다.

SPDX (Software Package Data Exchange): Linux Foundation에서 주도하는 SBOM 형식으로 주로 오픈소스 라이선스 컴플라이언스로 사용하기 위한 목적으로 생성합니다. 다만 구조가 복잡하고 취약점 정보를 직접 지원하지 않는다는 단점이 있습니다. (*참고: https://spdx.dev/)
- SPDX 2.2 (.spdx, .json, .xml, .xlsx)
- SPDX 2.3 (.spdx, .json, .xml, .xlsx)
- SPDX 3.0 (.json)
SWID(Software Identification Tag): NIST 및 ISO 표준을 기반으로 만든 SBOM 형식이며 주로 설치된 상용 소프트웨어를 추적하고 관리하기 위해서 만들어졌습니다. 엔터프라이즈 기업의 자산을 관리하거나 정부 조달에 지원하는 경우에 효과적입니다.
- SWID (.zip)
CycloneDX: OWASP에서 주도하는 SBOM 형식이며 소프트웨어 공급망 보안 및 취약점 대응을 목적으로 사용됩니다. CVE, VEX 등 보안에 관련된 정보 중심으로 작성되어 있으며 구조가 상대적으로 간결하고 명확하며 파싱 속도가 빠르다는 장점이 있습니다. (*참고: https://cyclonedx.org/)
- CycloneDX 1.4 (.json)
- CycloneDX 1.5 (.json)
- CycloneDX 1.6 (.json)
- NIS‑SBOM표준: 국가정보원(NIS)이 제시한 NIS‑SBOM 표준은 국내 소프트웨어 공급망 보안을 강화하기 위해 마련된 지침입니다. 15개 핵심 속성으로 구성되어 있으며 구성요소 식별 및 라이선스, 해시, 의존 관계 등 기본 정보와 취약점 정보 연동 항목이 포함되어 있습니다.
- NIS SBOM표준 (v1.0) (.csv)
- NIS SBOM표준 (v1.0) (.json)
- NIS SBOM표준 (v1.0) (.pdf)

결과 코드 모음

사용자가 요청한 분석이 정상적으로 완료되지 않은 경우 Sparrow On-Demand에서는 다음과 같은 결과 코드를 반환합니다.

결과 코드(ResultCode)	설명
`VCS_REQUEST_EXCEPTION`	분석 요청에 잘못된 URL이나 브랜치 정보 등 VCS 정보에 유효하지 않은 값을 입력했습니다.
`VCS_EXCEPTION`	위의 유효하지 않은 입력값 이외에 VCS 정보와 관련하여 잘못된 요청을 전송했습니다.
`ANALYSIS_SOURCE_DOWNLOAD_FAIL`	분석 소스를 다운로드하지 못했습니다.
`CLIENT_EXCEPTION`	소스 코드를 전처리하는 과정에서 오류가 발생했습니다
`STORAGE_REQUEST_EXCEPTION`	분석 요청에 잘못된 object나 bucket 등 Object Storage 정보에 유효하지 않은 값을 입력했습니다.
`STORAGE_EXCEPTION`	위의 유효하지 않은 입력값 이외에 Object Storage 정보와 관련하여 잘못된 요청을 전송했습니다.
`SERVICE_DISCONNECT`	분석 엔진에 대한 연결에 실패했습니다.
`SERVICE_REQUEST_EXCEPTION`	분석 엔진에 대한 요청에 실패했습니다.
`TARGET_ACCESS_FAIL`	웹취약점 분석에서 사용자가 입력한 웹 페이지 URL에 접근할 수 없습니다.
`RECORD_FILE_INVALID`	웹취약점 분석에서 사용자가 입력한 로그인 기록 파일이 유효하지 않습니다.
`ANALYSIS_STOP`	사용자가 요청한 분석 중지로 인해 분석이 중지되었습니다.
`ANALYSIS_ON_FAILURE`	분석 엔진이 실행 도중 실패했습니다.
`ANALYSIS_WORKER_ASSIGN_FAIL`	분석기가 배정되지 않았으므로 분석에 실패했습니다.
`ANALYSIS_WORKER_NOT_WORKING`	분석기가 배정되었지만 종료되었거나, 다른 작업이 진행 중이므로 분석에 실패했습니다.
`ANALYSIS_WORKER_STOP_FAIL`	사용자가 분석 중지를 요청했지만 분석이 완전히 중지되지 않았습니다.
`ISSUE_SAVE_FAIL`	분석 결과로 검출된 이슈를 저장하는데 실패했습니다.
`COMPONENT_SAVE_FAIL`	분석 결과로 검출된 컴포넌트를 저장하는데 실패했습니다.
`ISSUE_SIMILARITY_MODULE_FAIL`	유사 이슈 추천 모듈을 실행하는데 실패했습니다.
`POLICY_MAX_SOURCE_SIZE`	분석할 소스가 허용된 크기를 초과했습니다.
`CREATE_RESULT_FILE_FAIL`	분석 결과 파일을 생성하는데 실패했습니다.
`SBOM_CREATE_FAIL`	SBOM을 생성하는데 실패했습니다.
`ANALYSIS_NOT_FOUND`	요청한 분석이 존재하지 않습니다
`SERVER_EXCEPTION`	알 수 없는 예외가 발생했습니다.
`INVALID_AUTH`	사용자의 인증 정보가 유효하지 않습니다.
`ACCESS_DENIED`	사용자에게 권한이 없습니다.
`INVALID_AUTH`	invalid token
`INVALID_DATA`	요청한 값이 올바르지 않을 때 발생하는 예외입니다.
`INACTIVE_STATUS`	비활성화 상태의 계정입니다.
`NO_DATA`	요청한 자료가 존재하지 않습니다.
`REQUEST_NOT_DONE`	요청이 아직 수행중입니다.
`REQUEST_NOT_FOUND`	분석 요청이 존재하지 않습니다.
`INVALID_RESULT_SCHEMA_VERSION`	resultSchemaVersion 값이 올바르지 않습니다.
`ANALYSIS_STOP_INVALID_TARGET`	중지대상이 올바르지 않습니다.
`ANALYSIS_TOOL_TYPE_INVALID`	toolType 값이 유효하지 않습니다.
`ANALYSIS_STOP_ALREADY_COMPLETED`	중지대상의 상태가 이미 중지 또는 완료되었습니다.
`POLICY_DEFINITION`	분석 정책 정의가 올바르지 않습니다.
`POLICY_EXPIRE_TIME`	분석 정책(유효 기간)에 위배됐습니다.
`POLICY_REQUEST_COUNT`	분석 정책(분석 횟수)에 위배됐습니다.
`DATA_PARSING_FAIL`	데이터 파싱에 실패했습니다.

빠른 시작​

사용 가이드​

계정 등록​

토큰 발급​

분석 요청과 콜백​

분석 결과 파일​

라이선스 고지문​

SBOM​

결과 코드 모음​