본문으로 건너뛰기
버전: 2508.1

Sparrow On-Demand Node SDK

Node SDK를 사용하면 Sparrow On-Demand API를 직접 호출하지 않고도 소스코드 분석, 오픈소스 분석, 웹취약점 분석을 쉽게 수행할 수 있습니다.

Tip: Sparrow On-Demand Node SDK는 Typescript를 지원합니다.


목차​


환경 설정​

  • Node 20 이상 설치

  • npm 설정

    npm install @sparrowai/ondemand-node-sdk

  • Sparrow On-Demand API 토큰 필요

    Tip: 토큰 발급을 참고하세요.


초기화​

API를 호출할 클라이언트 객체 OndemandNodeClient를 생성하세요. OndemandClientConfig로 설정값을 지정할 수 있습니다.

import { OndemandNodeClient, OndemandClientConfig } from "@sparrowai/ondemand-node-sdk";
// config
const config = new OndemandClientConfig({ apiKey: "API_KEY" });

// create client
const client = new OndemandNodeClient(config);
  • apiKey API 요청에서 인증에 사용하기 위해 Sparrow On-Demand에서 발급 받은 토큰(API_KEY)입니다.

분석 요청​

공통 메소드​

Node SDK에서는 소스코드 분석, 오픈소스 분석, 웹취약점 분석과 같이 분석 유형에 따라 다음과 같은 메소드를 제공합니다.

const requestInfo = await client.doAnalysis(analysisRequest);

소스코드 분석​

import { getSastAnalysisRequest } from "@sparrowai/ondemand-node-sdk";

const sastVcsRequest = getSastAnalysisRequest({
  analysisSource: {
    type: 'Vcs',
    source: {
      url: 'https://github.com/jhkim593/PayProject.git',
      branch: 'master',
      authToken: 'authToken',
    },
  }
  options: {
    extensions: ['java'],
    issueSimilarity: true,
  },
  callbacks: [
    {
      url: 'url',
      type : ['ANALYSIS_PROGRESS'],
      headers: { key: 'key', value: 'value' }
    },
  ],
})

const requestInfo = await client.doAnalysis(sastVcsRequest);
  • callbacks 콜백 목록 List
    • type 콜백 이벤트 유형
      • ANALYSIS_COMPLETE : 분석 종료 이벤트만 수신
      • ANALYSIS_PROGRESS : 분석 종료를 제외한 분석 진행 이벤트를 수신
      • SRC_UPLOAD : 소스 업로드
    • url 콜백 URL
    • headers 헤더 목록
      • key 콜백 헤더 키
      • value 콜백 헤더 값
🔽 소스코드 분석 옵션

  • sastOptions

    • analysisSource

      • VCS

        • url VCS URL 필수 string
        • branch 브랜치 string
        • commitId 커밋 ID string
        • tag 태그 string
        • id VCS ID string
        • password VCS 비밀번호 string
        • authToken VCS 토큰 string

        Tip: url만 입력하는 경우 Git 저장소에 기본값으로 설정된 브랜치의 최신 커밋에 포함된 파일을 분석합니다.

      • ObjectStorage

        • endPoint 스토리지 엔드포인트 필수 string
        • bucket 스토리지 버킷 필수 string
        • object 스토리지 오브젝트 이름 필수 string
        • accessKey 스토리지 액세스 키 string
        • secretKey 스토리지 시크릿 키 string

    • extensions 분석 대상 파일 확장자 목록

      Tip: 다음 중 하나와 같이 입력하세요.

      • ["java", "go"]
      • ["*"] 압축 파일의 경우 압축 파일의 확장자가 분석 대상자에 해당하면 압축 파일 안에 있는 모든 파일이 분석에 포함됩니다.

    • excludedPath 분석 제외 경로

      Tip: 대소문자를 구분하지 않으며 *를 사용할 수 있습니다.

      • *AA*: AA가 포함된 모든 문자열과 일치
      • AA* : AA로 시작하는 모든 문자열과 일치 다른 방법으로 분석 제외 경로를 설정하려는 경우 아래를 참고하세요.

    • maxSourceSize 최대 소스 크기 number 소스코드 분석 또는 오픈소스 분석에서 검사할 분석 대상의 최대 크기입니다. 소스코드 분석 또는 오픈소스 분석을 수행하는 동안 내려받은 분석 대상의 크기가 SOURCE_SIZE보다 크면 분석이 종료됩니다. 1부터 200 사이의 정수를 입력할 수 있습니다.(단위: MB)

Tip: RequestInfo 객체를 반환합니다.


오픈소스 분석​

import { getScaAnalysisRequest } from "@sparrowai/ondemand-node-sdk";

const scaObjectStorageRequest = getScaAnalysisRequest({
  analysisSource: {
    type: 'ObjectStorage',
    source: {
      bucket: 'bucket',
      object: 'object',
      accessKey: 'accessKey',
      secretKey: 'secretKey',
    },
  }
  options: {
    sbomCreatorEmail : 'email'
  },
  callbacks: [
    {
      url: 'url',
      type : ['ANALYSIS_PROGRESS'],
      headers: { key: 'key', value: 'value' }
    },
  ],
})

const requestInfo = await client.doAnalysis(scaObjectStorageRequest);
  • callbacks 콜백 목록 List
    • type 콜백 이벤트 유형
      • ANALYSIS_COMPLETE : 분석 종료 이벤트만 수신
      • ANALYSIS_PROGRESS : 분석 종료를 제외한 분석 진행 이벤트를 수신
      • SRC_UPLOAD : 소스 업로드
    • url 콜백 URL
    • headers 헤더 목록
      • key 콜백 헤더 키
      • value 콜백 헤더 값
🔽 오픈소스 분석 옵션

  • scaOptions

    • analysisSource

      • VCS

        • url Git URL 필수 string
        • branch 브랜치 string
        • commitId 커밋 ID string
        • tag 태그 string
        • id VCS ID string
        • password VCS 비밀번호 string
        • authToken VCS 토큰 string

        Tip: url만 입력하는 경우 Git 저장소에 기본값으로 설정된 브랜치의 최신 커밋에 포함된 파일을 분석합니다.

      • ObjectStorage

        • endPoint 스토리지 엔드포인트 필수 string
        • bucket 스토리지 버킷 필수 string
        • object 스토리지 오브젝트 이름 필수 string
        • accessKey 스토리지 액세스 키 string
        • secretKey 스토리지 시크릿 키 string

    • extensions 분석 대상 파일 확장자 목록

      Tip: 다음 중 하나와 같이 입력하세요.

      • ["java", "go"]
      • ["*"] 압축 파일의 경우 압축 파일의 확장자가 분석 대상자에 해당하면 압축 파일 안에 있는 모든 파일이 분석에 포함됩니다.

    • excludedPath 분석 제외 경로

      Tip: 대소문자를 구분하지 않으며 *를 사용할 수 있습니다.

      • *AA*: AA가 포함된 모든 문자열과 일치
      • AA* : AA로 시작하는 모든 문자열과 일치 다른 방법으로 분석 제외 경로를 설정하려는 경우 아래를 참고하세요.

    • maxSourceSize 최대 소스 크기 number 소스코드 분석 또는 오픈소스 분석에서 검사할 분석 대상의 최대 크기입니다. 소스코드 분석 또는 오픈소스 분석을 수행하는 동안 내려받은 분석 대상의 크기가 SOURCE_SIZE보다 크면 분석이 종료됩니다. 1부터 200 사이의 정수를 입력할 수 있습니다.(단위: MB)

    • sbomTypes SBOM 유형 목록 빈 목록의 경우 SBOM을 생성하지 않습니다. 다음과 같은 값을 입력할 수 있습니다.

      • SPDX 2.2: SPDX22 (.spdx), SPDX22_JSON (.json), SPDX22_SPREADSHEET (.xlsx), SPDX22_RDF (.rdf)
      • SPDX 2.3: SPDX23 (.spdx), SPDX23_JSON (.json), SPDX23_SPREADSHEET (.xlsx), SPDX23_RDF (.rdf)
      • SPDX 3.0: SPDX30_JSON (.json)
      • CycloneDX: CycloneDX14, CycloneDX15, CycloneDX16 (.json)
      • SWID: SWID (.zip)
      • NIS SBOM: NIS_CSV (.csv), NIS_PDF (.pdf), NIS_JSON (.json)

    • sbomCreatorUsername SBOM 생성자 string

    • sbomCreatorEmail SBOM 생성자 이메일 string

Tip: RequestInfo 객체를 반환합니다.


웹취약점 분석​

import { getDastAnalysisRequest } from "@sparrowai/ondemand-node-sdk";

const dastRequest = getDastAnalysisRequest({
  options : {
    crawlerTargetSeedUrls : ['url'],
  },
  callbacks : [
    {
      url : 'url',
      type : ['ANALYSIS_COMPLETE'],
      headers : { key: 'key', value: 'value' }
    }
  ]
})
const requestInfo = await client.doAnalysis(dastRequest);
  • callbacks 콜백 목록 List
    • type 콜백 이벤트 유형
      • ANALYSIS_COMPLETE : 분석 종료 이벤트만 수신
      • ANALYSIS_PROGRESS : 분석 종료를 제외한 분석 진행 이벤트를 수신
      • SRC_UPLOAD : 소스 업로드
    • url 콜백 URL
    • headers 헤더 목록
      • key 콜백 헤더 키
      • value 콜백 헤더 값
🔽 웹취약점 분석 옵션

  • targetUrl 분석 대상 URL 필수 string

  • commonRecordsLogin 로그인 기록 파일 string

    Tip: Sparrow Event Clipboard를 다운로드하고 로그인 과정을 파일로 저장해서 사용하세요.

  • crawlerTargetContainEntireSeed 하위 경로만 수집 boolean

  • crawlerRequestAcceptLanguage 클라이언트 언어

    Tip: ko_KR과 같은 로케일 형식으로 입력하세요.

  • crawlerCrawlMaxUrl 최대 수집 URL 수 number

    Tip: 수집할 수 있는 URL의 개수를 제한하지 않으려면 기본값인 0을 입력하세요.

  • crawlerCrawlTimeout 최대 수집 시간 number

    Tip: 수집할 수 있는 시간을 제한하지 않으려면 기본값인 0을 입력하세요.

  • analyzerAnalyzeTimeout 최대 분석 시간 number

    Tip: 분석할 수 있는 시간을 제한하지 않으려면 기본값인 0을 입력하세요.

  • crawlerSkipUrl 제외할 수집 URL string

  • analyzerSkipUrl 제외할 분석 URL string

  • crawlerSkipUrlSuffix 제외할 URL 접미사 string

  • crawlerExcludeCssSelector 이벤트 수행 제외 요소 (CSS 선택자)

  • crawlerIncludeCssSelector 이벤트 수행 추가 요소 (CSS 선택자)

  • crawlerExcludeXpath 이벤트 수행 제외 요소 (XPath)

  • crawlerIncludeXpath 이벤트 수행 추가 요소 (XPath)

  • crawlerRequestCustomHeaders 사용자 정의 HTTP 헤더

  • crawlerLimitUrlDepthDegree URL 수집 깊이

    Tip: high, medium, low으로 입력하세요.

  • crawlerLimitDomDepthDegree DOM 수집 깊이

    Tip: high, medium, low으로 입력하세요.

  • crawlerBrowserExplicitTimeout 이벤트 대기 시간 number

  • crawlerRequestCountPerSecond HTTP 요청 횟수 number

    Tip: 전송할 수 있는 HTTP 요청의 개수를 제한하지 않으려면 기본값인 -1을 입력하세요.

  • crawlerClientTimeout HTTP 클라이언트 대기 시간 number

Tip: RequestInfo 객체를 반환합니다.


상태 조회​

요청 상태 조회​

분석을 요청한 후 요청 상태를 확인할 수 있습니다.

const requestInfo = await client.getRequest(requestId: number)
  • requestId 요청 ID 필수 number

Tip: RequestInfo 객체를 반환합니다.


분석 상태 조회​

분석이 시작된 후 분석 ID를 통해 분석 상태를 확인할 수 있습니다.

const analysisInfo = await client.getAnalysis(analysisId: number)
  • analysisId 분석 ID 필수 number

Tip: AnalysisInfo 객체를 반환합니다.


분석 결과 파일 다운로드​

분석이 완료된 후에 분석 결과를 파일로 다운로드 받을 수 있습니다.

await client.downloadAnalysisResult(analysisId: number, filePath: string);

  • analysisId 분석 ID 필수 number

  • filePath 다운로드 경로 필수 string

    Tip : 다운로드 경로에는 zip 확장자가 포함된 파일 이름을 입력하세요. /home/result.zip


분석 결과 읽어오기​

분석이 완료되면 결과 파일을 다운로드하고 압축을 해제한 후에 도구별 Reader 객체를 통해 결과를 읽어올 수 있습니다.

공통 메소드​

const resultReader = client.getAnalysiResultReader<T extends ResultReader>(analysisId: number ,filePath: string);

소스코드 분석 결과 읽어오기​

import { SastResultReader } from "@sparrowai/ondemand-node-sdk/types";

// 1. SastResultReader 생성
const sastResultReader = await client.getAnalysiResultReader<SastResultReader>(analysisId: number ,filePath: string);

// 2. 분석 결과 요약 읽어오기 
const sastSummary : SastSummary = sastResultReader.readSummary();

// 3. 분석 자산 목록 읽어오기
const assets : string[] = sastResultReader.readAsset();

// 4. 이슈 파일의 개수 반환하기
const size : number = sastResultReader.issueSize();

// 5. 이슈 파일에서 SastIssue 목록 반환하기
const sastIssues : SastIssue[] = sastResultReader.readIssue(index: number);

// 6. 작업 메시지에서 WorkMessage 목록 반환하기
const workMessages : WorkMessage[] = sastResultReader.readWorkMessage();

  • SastResultReader

    • analysisId 분석 ID 필수 number
    • filePath 다운로드 경로 필수 string

  • readSummary 분석 결과 요약 읽어오기 메소드

  • readAsset 분석 자산 목록 읽어오기 메소드

    Tip: string[]을 반환합니다.

  • issueSize 이슈 파일의 개수 반환하기 메소드

    Tip: number 를 반환합니다.

  • readIssue SastIssue 목록 반환하기 메소드

    • index

      Tip: SastIssue[]를 반환하며 최대값은 issueSize() 메소드를 통해 확인할 수 있습니다.

  • readWorkMessage WorkMessage 목록 반환하기 메소드

    Tip: WorkMessage[]를 반환합니다.


오픈소스 분석 결과 읽어오기​

import { ScaResultReader, SbomType } from "@sparrowai/ondemand-node-sdk/types";

// 1. ScaResultReader 생성
const scaResultReader = await client.getAnalysiResultReader<ScaResultReader>(analysisId: number ,filePath: string);

// 2. 분석 결과 요약 읽어오기 
const scaSummary : ScaSummary = scaResultReader.readSummary();

// 3. 분석 자산 목록 읽어오기
const assets : string[] = scaResultReader.readAsset();

// 4. 이슈 파일의 개수 반환하기
const size : number = scaResultReader.issueSize();

// 5. 이슈 파일에서 SastIssue 목록 반환하기
const scaComponents : ScaComponent[] = scaResultReader.readIssue(index: number);

// 6. 작업 메시지에서 WorkMessage 목록 반환하기
const workMessages : WorkMessage[] = scaResultReader.readWorkMessage();

// 7. SBOM 파일 경로 반환하기
const sbomPath : string = scaResultReader.getSbomPath(sbomType: SbomType);
// ex. const sbomPath : string = scaResultReader.getSbomPath(SbomType.SPDX22);

// 8. 라이선스 고지문 파일(HTML) 경로 반환하기
const path : string = scaResultReader.getLicenseNoticeHtmlPath();

// 9. 라이선스 고지문 파일(Markdown) 경로 반환하기
const path : string = scaResultReader.getLicenseNoticeMarkDownPath();

// 10. 라이선스 고지문 파일(Text) 경로 반환하기
const path : string = scaResultReader.getLicenseNoticeTextPath();

  • SastResultReader

    • analysisId 분석 ID 필수 number
    • filePath 다운로드 경로 필수 string

  • readSummary 분석 결과 요약 읽어오기 메소드

  • readAsset 분석 자산 목록 읽어오기 메소드

    Tip: string[]을 반환합니다.

  • issueSize 이슈 파일의 개수 반환하기 메소드

    Tip: number를 반환합니다.

  • readIssue SastIssue 목록 반환하기 메소드

    • index

      Tip: SastIssue[]를 반환하며 최대값은 issueSize() 메소드를 통해 확인할 수 있습니다.

  • readWorkMessage WorkMessage 목록 반환하기 메소드

    Tip: WorkMessage[]를 반환합니다.

  • getSbomPath SBOM 파일 경로 반환하기 메소드

    • sbomType SBOM 타입 필수

    Tip: SBOM 파일 경로 sbomPath를 반환합니다.

  • getLicenseNoticeHtmlPath 라이선스 고지문 파일(HTML) 경로 반환하기 메소드

    Tip: 라이선스 고지문 파일 경로 path를 반환합니다.

  • getLicenseNoticeMarkDownPath 라이선스 고지문 파일(Markdown) 경로 반환하기 메소드

    Tip: 라이선스 고지문 파일 경로 path를 반환합니다.

  • getLicenseNoticeTextPath 라이선스 고지문 파일(Text) 경로 반환하기 메소드

    Tip: 라이선스 고지문 파일 경로 path를 반환합니다.


웹취약점 분석 결과 읽어오기​

import { DastResultReader } from "@sparrowai/ondemand-node-sdk/types";

// 1. DastResultReader 생성
const dastResultReader = await client.getAnalysiResultReader<DastResultReader>(analysisId: number ,filePath: string);

// 2. 분석 결과 요약 읽어오기 
const dastSummary : DastSummary = dastResultReader.readSummary();

// 3. 분석 자산 목록 읽어오기
const assets : string[] = dastResultReader.readAsset();

// 4. 이슈 파일의 개수 반환하기
const size : number = dastResultReader.issueSize();

// 5. 이슈 파일에서 SastIssue 목록 반환하기
const dastIssues : DastIssue[] = dastResultReader.readIssue(index: number);

// 6. 작업 메시지에서 WorkMessage 목록 반환하기
const workMessages : WorkMessage[] = dastResultReader.readWorkMessage();

  • SastResultReader

    • analysisId 분석 ID 필수 number
    • filePath 다운로드 경로 필수 string

  • readSummary 분석 결과 요약 읽어오기 메소드

  • readAsset 분석 자산 목록 읽어오기 메소드

    Tip: string[]을 반환합니다.

  • issueSize 이슈 파일의 개수 반환하기 메소드

    Tip: number를 반환합니다.

  • readIssue SastIssue 목록 반환하기 메소드

    • index

      Tip: SastIssue[]를 반환하며 최대값은 issueSize() 메소드를 통해 확인할 수 있습니다.

  • readWorkMessage WorkMessage 목록 반환하기 메소드

    Tip: WorkMessage[]를 반환합니다.


분석 중지​

진행 중인 분석을 중지할 수 있습니다.

await client.stopAnalysis(analysisId: number);
  • analysisId 분석 ID 필수 number

Tip: 아무 것도 반환하지 않습니다.


예외 처리​

초기화에서 생성한 OndemandNodeClient 인스턴스의 메소드를 호출하여 분석을 수행할 수 있습니다. 메소드를 실행할 때 OndemandException이 발생한 경우 의미와 처리 방법은 아래를 참고하세요. OndemandException은 RuntimeException을 통해 예외를 전달하며 두가지로 분류됩니다.

  • OndmandClientException 클라이언트에서 Sparrow On-Demand에 요청을 보내거나 Sparrow On-Demand에서 응답을 처리할 때 발생할 수 있습니다.
    • resultCode 결과 코드 string 예외 발생 원인에 따라 다른 코드가 표시됩니다. 자세한 내용은 결과 코드를 참고하세요.
    • message 메시지 string 예외 발생 원인에 대한 메시지입니다.
  • OndmandServerException Sparrow On-Demand에서 성공적으로 요청을 받았지만 처리하지 못한 경우 발생합니다.
    • resultCode 결과 코드 string 예외 발생 원인에 따라 다른 코드가 표시됩니다. 자세한 내용은 결과 코드를 참고하세요.
    • message 메시지 string 예외 발생 원인에 대한 메시지입니다.
    • statusCode 상태 코드 number 응답 상태 코드를 나타냅니다.
    • validationErrors 유효성 오류 메시지 string 요청에 대한 유효성 검증에 실패한 경우 서버에서 반환되는 메시지입니다.

객체 정보​

RequestInfo​

  • requestId 요청 ID number
  • result 요청 결과 string 분석이 종료된 결과이며 다음과 같은 값을 가집니다.
    • SUCCESS: 분석이 성공적으로 완료된 상태
    • FAIL: 분석을 올바르게 완료하지 못하고 실패한 상태
    • STOP: 중지 요청을 받아 분석이 중지된 상태
  • analysisList 분석 목록 AnalysisInfo[]

    Tip: AnalysisInfo 객체의 목록입니다.


AnalysisInfo​

  • analysisId 분석 ID number
  • requestId 요청 ID number
  • status 분석 상태 string
    분석이 진행되는 단계에 따른 상태이며 다음 중 하나로 표시됩니다.
    • STOP_PROCESS: 중지 요청을 받고 분석을 중지하는 중
    • INIT : 분석 수행을 위해 환경을 준비하는 중
    • READY: 환경이 구성되고 분석 대상을 준비하는 중
    • PRE_PROCESS: 분석을 위해 분석 대상을 전처리하는 중
    • ANALYSIS: 분석을 수행하는 중
    • POST_PROCESS: 분석이 끝나고 결과를 처리하는 중
    • COMPLETE: 분석이 종료된 상태
  • toolType 분석 유형 string
  • memo 메모 string