Sparrow On-Demand Node SDK

Node SDK를 사용하면 Sparrow On-Demand API를 직접 호출하지 않고도 소스코드 분석, 오픈소스 분석, 웹취약점 분석을 쉽게 수행할 수 있습니다. Sparrow OnDemand에서 제공하는 Node SDK를 활용하여 솔루션을 소프트웨어 개발 프로세스에 통합하세요.

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);

• analysisRequest: 분석 유형별 요청 객체
  • SastAnalysisRequest 소스코드 분석
  • ScaAnalysisRequest 오픈소스 분석
  • DastAnalysisRequest 웹취약점 분석

소스코드 분석

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: 'key1', value: 'value1' },
        { key: 'key2', value: 'value2' },
        { key: 'key3', value: 'value3' }
      ]
    },
  ],
})

const requestInfo = await client.doAnalysis(sastVcsRequest);

SastAnalysisReqeust.builder 소스코드 분석 요청 빌더 메소드

• callbacks 콜백 목록 List

  콜백이란 분석 요청 API를 호출하고 난 다음, 분석이 진행되며 특정 이벤트가 완료되었을 때 수신할 수 있는 웹훅 콜백을 의미합니다. callbacks를 입력하여 사용자가 실행한 분석이 진행되는 과정에 대한 정보를 수신하세요.

  콜백 목록에는 of 메소드를 사용해서 CallbackType, CallbackHeader 클래스로 콜백 목록을 설정하거나 콜백 목록 대신 콜백 형식인 SrcUploadCallback, CompleteCallback, ProgressCallback, DastProgressCallback 클래스를 설정할 수 있습니다.

  • SrcUploadCallback: 소스 업로드 콜백
  • CompleteCallback : 완료 콜백
  • ProgressCallback : 진행 콜백
  • DastProgressCallback : 웹취약점 분석 진행 콜백

• sastOptions 소스코드 분석 옵션 소스코드 분석과 관련된 옵션입니다.

  • SastOptionRequest.builder 소스코드 분석 옵션 빌더 메소드

  • analysisSource 분석 대상 분석 대상에 대한 정보입니다. 소스코드 분석 또는 오픈소스 분석의 경우 VCS 혹은 오브젝트 스토리지에 있는 소스를 분석할 수 있습니다.

    • AnalysisSourceRequest.VCS.builder VCS 빌더 메소드 VCS 저장소에 있는 소스를 분석합니다. vcsInfo에 해당하는 정보를 입력하세요.

      • url VCS URL 필수 String 분석할 파일이 저장된 저장소의 URL(VCS_URL)입니다. 이 값만 입력하는 경우 Git 저장소에 기본값으로 설정된 브랜치의 최신 커밋에 포함된 파일을 분석합니다.

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

      • branch 브랜치 String

      • commitId 커밋 ID String

      • tag 태그 String

      • id VCS ID String

      • password VCS 비밀번호 String

      • authToken VCS 토큰 String

        Tip: VCS 저장소의 인증 정보입니다. 저장소에 접근하기 위해 인증이 필요한 경우 입력해야 합니다. password와 authToken이라는 두 가지 값 중 하나를 사용합니다.

    • AnalysisSourceRequest.ObjectStorage.builder 오브젝트 스토리지 빌더 메소드 오브젝트 스토리지에 있는 소스를 분석합니다. objectStorage에 해당하는 정보를 입력하세요.

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

  • extensions 분석 대상 파일 확장자 목록 소스코드 분석은 분석 대상에 포함시킬 파일을 확장자(FILE_EXTENSION1, FILE_EXTENSION2)로 구분합니다. 여기에 해당하지 않는 파일은 분석에서 제외됩니다. *로 입력하는 경우 모든 파일을 분석합니다.

    입력 예시

    • ["java", "go"]
    • ["*"]

    Tip: 압축 파일의 경우 압축 파일의 확장자가 분석 대상에 해당하면 압축 파일 안에 있는 모든 파일이 분석에 포함됩니다.

  • excludedPath 분석 제외 경로 분석에서 제외할 파일이 있는 경우 해당 파일의 경로(EXCLUDED_PATH1, EXCLUDED_PATH2, EXCLUDED_PATH3)를 입력합니다. 여기에 입력한 경로에 포함된 파일로부터 이슈가 검출되지 않게 됩니다.

    입력 예시

    • /User/jkw/ddde
    • /home/sparrow/*
    • \*/dev/\*

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

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

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

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

오픈소스 분석

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: 'key1', value: 'value1' },
        { key: 'key2', value: 'value2' },
        { key: 'key3', value: 'value3' }
      ]
    },
  ],
})

const requestInfo = await client.doAnalysis(scaObjectStorageRequest);

ScaAnalysisReqeust.builder 오픈소스 분석 요청 빌더 메소드

• callbacks 콜백 목록 List

  콜백이란 분석 요청 API를 호출하고 난 다음, 분석이 진행되며 특정 이벤트가 완료되었을 때 수신할 수 있는 웹훅 콜백을 의미합니다. callbacks를 입력하여 사용자가 실행한 분석이 진행되는 과정에 대한 정보를 수신하세요.

  콜백 목록에는 of 메소드를 사용해서 CallbackType, CallbackHeader 클래스로 콜백 목록을 설정하거나 콜백 목록 대신 콜백 형식인 SrcUploadCallback, CompleteCallback, ProgressCallback, DastProgressCallback 클래스를 설정할 수 있습니다.

  • SrcUploadCallback: 소스 업로드 콜백
  • CompleteCallback : 완료 콜백
  • ProgressCallback : 진행 콜백
  • DastProgressCallback : 웹취약점 분석 진행 콜백

• scaOptions 오픈소스 분석 옵션 오픈소스 분석과 관련된 옵션입니다.

  • ScaOptionRequest.builder 오픈소스 분석 옵션 빌더 메소드

  • analysisSource 분석 대상 분석 대상에 대한 정보입니다. 소스코드 분석 또는 오픈소스 분석의 경우 VCS 혹은 오브젝트 스토리지에 있는 소스를 분석할 수 있습니다.

    • AnalysisSourceRequest.VCS.builder VCS 빌더 메소드 VCS 저장소에 있는 소스를 분석합니다. vcsInfo에 해당하는 정보를 입력하세요.

      • url VCS URL 필수 String 분석할 파일이 저장된 저장소의 URL(VCS_URL)입니다. 이 값만 입력하는 경우 Git 저장소에 기본값으로 설정된 브랜치의 최신 커밋에 포함된 파일을 분석합니다.

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

      • branch 브랜치 String

      • commitId 커밋 ID String

      • tag 태그 String

      • id VCS ID String

      • password VCS 비밀번호 String

      • authToken VCS 토큰 String

        Tip: VCS 저장소의 인증 정보입니다. 저장소에 접근하기 위해 인증이 필요한 경우 입력해야 합니다. password와 authToken이라는 두 가지 값 중 하나를 사용합니다.

    • AnalysisSourceRequest.ObjectStorage.builder 오브젝트 스토리지 빌더 메소드 오브젝트 스토리지에 있는 소스를 분석합니다. objectStorage에 해당하는 정보를 입력하세요.

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

  • excludedPath 분석 제외 경로 분석에서 제외할 파일이 있는 경우 해당 파일의 경로(EXCLUDED_PATH1, EXCLUDED_PATH2, EXCLUDED_PATH3)를 입력합니다. 여기에 입력한 경로에 포함된 파일로부터 이슈가 검출되지 않게 됩니다.

    입력 예시

    • /User/jkw/ddde
    • /home/sparrow/*
    • \*/dev/\*

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

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

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

  • sbomTypes SBOM 유형 목록 수신할 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: SimpleRequestInfo 객체를 반환합니다.

웹취약점 분석

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

const dastRequest = getDastAnalysisRequest({
  options : {
    crawlerTargetSeedUrls : ['url'],
  },
  callbacks : [
    {
      url : 'url',
      type : ['ANALYSIS_COMPLETE'],
      headers : [
        { key: 'key1', value: 'value1' },
        { key: 'key2', value: 'value2' },
        { key: 'key3', value: 'value3' }
      ]
    }
  ]
})
const requestInfo = await client.doAnalysis(dastRequest);

DastAnalysisRequest.builder 웹취약점 분석 요청 빌더 메소드

• callbacks 콜백 목록 List

  콜백이란 분석 요청 API를 호출하고 난 다음, 분석이 진행되며 특정 이벤트가 완료되었을 때 수신할 수 있는 웹훅 콜백을 의미합니다. callbacks를 입력하여 사용자가 실행한 분석이 진행되는 과정에 대한 정보를 수신하세요.

  콜백 목록에는 of 메소드를 사용해서 CallbackType, CallbackHeader 클래스로 콜백 목록을 설정하거나 콜백 목록 대신 콜백 형식인 SrcUploadCallback, CompleteCallback, ProgressCallback, DastProgressCallback 클래스를 설정할 수 있습니다.

  • SrcUploadCallback: 소스 업로드 콜백
  • CompleteCallback : 완료 콜백
  • ProgressCallback : 진행 콜백
  • DastProgressCallback : 웹취약점 분석 진행 콜백

• dastOptions 웹취약점 분석 옵션 웹취약점 분석과 관련된 옵션입니다.

  • DastOptionRequest.builder 웹취약점 분석 옵션 빌더 메소드

    • crawlerTargetSeedUrls 분석 대상 URL 필수 String 분석할 URL이며 하나만 입력할 수 있습니다.

    분석 대상 URL을 입력할 때는 해당 URL에 외부 인터넷이 접근할 수 있는지, 해당 서버에 방화벽이 동작하고 있지 않은지 확인해야 합니다.

    • commonRecordsLogin 로그인 기록 파일 string 로그인 기록 파일은 이벤트 클립보드에서 저장한 .ecl 형식의 파일로써 특정 URL에서 사용자의 동작이 기록되어 있습니다. 주로 사용자가 특정 URL에서 로그인하는 데 사용한 ID 및 비밀번호 정보를 저장하여 URL을 수집하거나 분석할 때 사용합니다.

    로그인 기록 파일을 첨부하는 경우 URL 수집 및 분석 중에 이벤트 클립보드의 기록이 시작된 URL에 도달하면 해당 파일에 저장된 사용자의 동작을 그대로 재현하게 됩니다. 이러한 방법으로 로그인 페이지에서 필요한 인증을 통과할 수 있습니다.

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

    • crawlerTargetContainEntireSeed 하위 경로만 수집 boolean 하위 경로만 수집은 프로젝트에 입력한 분석 대상 URL을 모두 포함하는 경로만 수집하는지를 의미하며 true, false로 구분합니다.(기본값: true) 이 옵션을 true로 설정하면 분석 대상 URL을 포함한 하위 경로만 분석하게 됩니다. 이 옵션을 false로 설정하면 프로젝트의 분석 대상 URL에 포함된 상위 경로도 분석하게 됩니다.

    • crawlerRequestAcceptLanguage 클라이언트 언어 분석 대상인 웹 애플리케이션이 표시되는 브라우저에서 어떤 언어를 설정했고, HTTP 클라이언트가 어떤 언어를 이해할 수 있는지 설정합니다. 언어로 표시되는 로케일 형식으로 입력할 수 있습니다.(기본값: ko)

      Tip: ko와 같은 형식으로 입력하세요.

    • crawlerCrawlMaxUrl 최대 수집 URL 수 integer 최대 수집 URL 수는 분석에서 수집할 수 있는 URL 수의 최대 개수입니다. 너무 많은 URL이 수집될 경우 분석 결과가 정확하지 않을 수 있습니다. 따라서 이 옵션에서 수집할 URL의 최대 개수를 지정하는 것이 좋습니다.(기본값: 0)

      이 옵션에 입력된 값이 클수록 수집할 수 있는 URL의 개수가 늘어나지만 수집을 위한 분석 시간도 증가할 수 있습니다. 이 옵션에 입력된 값이 적을수록 수집할 수 있는 URL 개수가 줄어들어 분석 시간도 줄어듭니다. 아무것도 입력하지 않는 경우 옵션의 기본값은 0이며 이 경우에 수집할 수 있는 URL의 개수를 제한하지 않게 됩니다.

    • crawlerCrawlTimeout 최대 수집 시간 integer

      최대 수집 시간은 분석에서 URL을 수집할 수 있는 최대 시간입니다. 너무 많은 시간이 걸리는 경우 분석 결과가 정확하지 않을 수 있습니다. 따라서 이 옵션에서 수집 시간을 지정하는 것이 좋습니다.(단위: 분, 기본값: 0)

      이 옵션에 입력된 값이 클수록 수집을 위한 분석 시간이 증가하고 수집할 수 있는 URL의 개수도 늘어날 수 있습니다. 이 옵션에 입력된 값이 적을수록 분석 시간이 감소하고 수집할 수 있는 URL의 개수가 줄어들 수 있습니다. 아무것도 입력하지 않는 경우 옵션의 기본값은 0이며 이 경우에 수집할 수 있는 시간을 제한하지 않게 됩니다.

    • analyzerAnalyzeTimeout 최대 분석 시간 integer

      최대 분석 시간은 분석에서 URL을 분석할 수 있는 최대 시간입니다. 너무 많은 시간이 걸리는 경우 분석 결과가 정확하지 않을 수 있습니다. 따라서 이 옵션에서 분석 시간을 지정하는 것이 좋습니다.(단위: 분, 기본값: 0)

      이 옵션에 입력된 값이 클수록 분석 시간이 증가하고 분석의 결과도 늘어날 수 있습니다. 이 옵션에 입력된 값이 적을수록 분석 시간이 감소하고 분석의 결과도 줄어들 수 있습니다. 아무것도 입력하지 않는 경우 옵션의 기본값은 0이며 이 경우에 분석할 수 있는 시간을 제한하지 않게 됩니다.

    • crawlerSkipUrl 제외할 수집 URL string 최대 분석 시간은 분석에서 URL을 분석할 수 있는 최대 시간입니다. 너무 많은 시간이 걸리는 경우 분석 결과가 정확하지 않을 수 있습니다. 따라서 이 옵션에서 분석 시간을 지정하는 것이 좋습니다.(단위: 분, 기본값: 0)

      이 옵션에 입력된 값이 클수록 분석 시간이 증가하고 분석의 결과도 늘어날 수 있습니다. 이 옵션에 입력된 값이 적을수록 분석 시간이 감소하고 분석의 결과도 줄어들 수 있습니다. 아무것도 입력하지 않는 경우 옵션의 기본값은 0이며 이 경우에 분석할 수 있는 시간을 제한하지 않게 됩니다.

    • analyzerSkipUrl 제외할 분석 URL string

      제외할 분석 URL은 URL에 특정 단어가 포함된 경우 해당 URL을 분석하지 않고 건너뛰는 문자열 목록을 가리킵니다. 하나 이상의 URL을 입력하고 엔터 또는 쉼표(,)로 구분할 수 있습니다.

      이 옵션에 입력한 목록에 해당하는 단어가 하나라도 분석하려는 URL에 포함되었다면 해당 URL을 분석하지 않게 됩니다.

      Tip: URL로 표시되는 페이지 전체가 아니라 페이지의 동작을 분석에서 제외하려는 경우 아래에 있는 이벤트 수행 제외 요소 옵션을 사용하세요.

    • crawlerSkipUrlSuffix 제외할 URL 접미사 string

      제외할 URL 접미사는 URL의 끝에 특정 단어나 확장자가 포함된 경우 해당 URL을 수집하지 않고 건너뛰는 접미사 목록을 가리킵니다. 마침표(.)로 시작하는 확장자 형식으로 입력하고 엔터 또는 쉼표(,)로 구분할 수 있습니다.(기본값: .js .jsx .ts .tsx .css .xml .jpg .jpeg .gif .bmp .png .ico .wma .wav .mp3 .wmv .avi .mp4 .mov .exe .zip .tar .tar.gz .7z .doc .xls .ppt .docx .xlsx .pptx .pdf .txt .csv .jar .eot .woff2 .woff .ttf .otf .apk .hwp .svg .msi`) 이 옵션에 입력한 목록에 해당하는 단어가 하나라도 수집하려는 URL의 끝에 포함되었다면 해당 URL을 수집하지 않게 됩니다. URL로 이동하기 전에 HTML 요소의 속성 값 등을 보고 건너뛰기 때문에 해당 URL에 방문하지 않으므로 파일 다운로드 등을 수행하기 전에 건너뛸 수 있습니다.

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

      이벤트 수행 제외 요소 (CSS 선택자)는 URL 수집 과정에서 브라우저가 이벤트를 수행할 때, 이벤트를 수행하지 않고 제외할 HTML 요소를 나타낸 CSS 선택자 목록입니다. 하나 이상의 값을 문자열로 입력하고 엔터 또는 쉼표(,)로 구분할 수 있습니다.

      이 옵션에 입력한 목록에 해당하는 CSS 선택자가 하나라도 페이지에 포함되었다면 해당하는 HTML 요소와 하위 HTML 요소의 이벤트를 모두 수행하지 않게 됩니다. 이러한 방법으로 페이지에서 로그아웃 버튼을 클릭하지 않도록 설정할 수 있습니다.

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

      이벤트 수행 추가 요소 (CSS 선택자)는 URL 수집 과정에서 이벤트 수행이 가능한 HTML 요소에 포함되지 않아도 이벤트를 무조건 수행할 HTML 요소를 나타낸 CSS 선택자 목록입니다. 하나 이상의 값을 문자열로 입력하고 엔터 또는 쉼표(,)로 구분할 수 있습니다.

      이 옵션에 입력한 목록에 해당하는 CSS 선택자가 하나라도 페이지에 포함되었다면 해당하는 HTML 요소와 하위 HTML 요소의 이벤트를 모두 수행하게 됩니다. 이러한 방법으로 페이지에서 이벤트에 포함되지 않는 태그와 같은 요소를 수행할 수 있습니다.

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

      이벤트 수행 제외 요소 (XPath)는 URL 수집 과정에서 브라우저가 이벤트를 수행할 때, 이벤트를 수행하지 않고 제외할 HTML 요소를 나타낸 XPath 목록입니다. 하나 이상의 값을 문자열로 입력하고 엔터 또는 쉼표(,)로 구분할 수 있습니다.

      이 옵션에 입력한 목록에 해당하는 XPath가 하나라도 페이지에 포함되었다면 해당하는 HTML 요소와 하위 HTML 요소의 이벤트를 모두 수행하지 않게 됩니다. 이러한 방법으로 페이지에서 로그아웃 버튼을 클릭하지 않도록 설정할 수 있습니다.

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

      이벤트 수행 추가 요소 (XPath)는 URL 수집 과정에서 이벤트 수행이 가능한 HTML 요소에 포함되지 않아도 이벤트를 무조건 수행할 HTML 요소를 나타낸 XPath 목록입니다. 하나 이상의 값을 문자열로 입력하고 엔터 또는 쉼표(,)로 구분할 수 있습니다.

      이 옵션에 입력한 목록에 해당하는 XPath가 하나라도 페이지에 포함되었다면 해당하는 HTML 요소와 그 하위 HTML 요소의 이벤트를 모두 수행하게 됩니다. 이러한 방법으로 페이지에서 이벤트에 포함되지 않는 태그와 같은 요소를 수행할 수 있습니다.

    • crawlerRequestCustomHeaders 사용자 정의 HTTP 헤더

      사용자 정의 HTTP 헤더는 URL을 수집할 때 전송할 HTTP 요청에 포함되는 헤더의 이름과 값의 목록을 가리킵니다. 이 옵션에 헤더의 이름과 값을 입력하면 해당 헤더를 모든 HTTP 요청 메시지에 추가하게 됩니다. 추가하기 버튼을 클릭하여 하나 이상의 헤더를 추가하고 휴지통 아이콘을 클릭하여 삭제할 수 있습니다.

      이 옵션에는 HTTP 요청에 반드시 필요한 헤더를 입력해야 합니다. 이로 인해 브라우저에 프록시를 설정하므로 수집 속도가 느려질 수 있습니다.

      Cookie 헤더를 제외하고 동일한 이름의 헤더를 여러 개 입력한 경우 그 중 하나만 적용됩니다. 따라서 여러 값을 입력해야 하는 경우 헤더 값을 ;로 구분하여 입력하세요. 같은 이름의 헤더가 이미 있는 경우 해당 헤더를 지우고 커스텀 헤더가 추가됩니다. 커스텀 헤더를 사용하려면 분석 대상 URL의 호스트가 localhost 또는 127.0.0.1로 설정되면 안됩니다. 로컬에 있는 웹 애플리케이션을 분석하려는 경우 로컬 IP 주소를 입력해야 합니다.

    • crawlerLimitUrlDepthDegree URL 수집 깊이

      URL 수집 깊이는 수집할 URL이 시작 URL에서부터 얼마나 멀리 떨어져 있는지를 의미하며 high, medium, low로 구분합니다. URL이 멀수록 시작 URL에서 특정 URL에 도달하기 위해 페이지 이동 등 수행해야 하는 최소한의 동작이 많아집니다.(기본값: medium)

      이 옵션을 high로 설정하면 시작 URL에서부터 멀리 있는 URL까지도 수집하게 되지만 수집하는 시간이 오래 걸립니다. 이 옵션을 low로 설정하면 프로젝트에서 URL을 수집하는 시간은 짧아지지만 멀리 있는 URL은 수집하지 않게 됩니다.

    • crawlerLimitDomDepthDegree DOM 수집 깊이

      DOM 수집 깊이는 수집할 DOM이 동일한 URL에서 생성된 첫 번째 DOM으로부터 얼마나 멀리 떨어져 있는지를 의미하며 high, medium, low로 구분합니다. DOM이 멀수록 첫 번째 DOM에서 동일한 URL의 특정 DOM에 도달하기 위해 수행해야 하는 최소한의 동작이 많아집니다.(기본값: medium)

      이 옵션을 high로 설정하면 URL로 이동할 때 생성되는 첫 DOM에서부터 멀리 있는 DOM까지도 수집하게 되지만 수집하는 시간이 오래 걸립니다. 이 옵션을 low로 설정하면 프로젝트에서 DOM을 수집하는 시간은 짧아지지만 멀리 있는 DOM은 수집하지 않게 됩니다.

    • crawlerBrowserExplicitTimeout 이벤트 대기 시간 integer

      이벤트 대기 시간은 이벤트를 수행할 때마다 이벤트 수행 결과가 DOM에 반영되기를 기다리는 시간을 가리킵니다. 0 이상 5000 이하의 숫자를 입력할 수 있으며 옵션을 입력하지 않은 경우 기본값은 300입니다.(단위: 밀리초, 기본값: 300)

      이 옵션에 입력된 값이 클수록 수행한 이벤트를 DOM에 반영하는데 시간이 걸리는 웹 애플리케이션의 URL을 수집할 수 있지만 수집하는 속도가 느려집니다. 이 옵션에 입력된 값이 적을수록 URL을 수집하는 속도는 향상되지만 DOM이 변경될 때 시간이 필요한 웹 애플리케이션의 URL을 수집하지 않게 됩니다.

    • crawlerRequestCountPerSecond HTTP 요청 횟수 integer

      HTTP 요청 횟수는 URL을 수집할 때 1초에 전송할 수 있는 HTTP 요청의 개수를 가리킵니다. -1 이상 10000 이하의 숫자를 입력할 수 있으며 옵션을 입력하지 않는 경우 기본값은 -1이며 이 경우에 전송할 수 있는 HTTP 요청의 개수를 제한하지 않게 됩니다.(단위: 개, 기본값: -1)

      이 옵션에 입력된 값이 클수록 1초에 전송할 수 있는 HTTP 요청의 개수가 늘어나서 URL을 수집하는 속도가 빨라지지만 트래픽량이 늘어나 분석 대상 웹 애플리케이션 서버에 부하도 늘어날 수 있습니다. 이 옵션에 입력된 값이 적을수록 트래픽량이 낮아져 분석 대상 웹 애플리케이션 서버의 부하도 줄어들지만 URL을 수집하는 속도가 늦어집니다.

    • crawlerClientTimeout HTTP 클라이언트 대기 시간 integer HTTP 클라이언트 대기 시간은 HTTP 클라이언트가 분석을 수행하기 위해 웹 서버에 연결하고, HTTP 요청을 보내고, HTTP 응답을 받는 과정에서 지연이 발생했을 때 기다리는 최대 시간을 가리킵니다. 0 이상 30000 이하의 숫자를 입력할 수 있으며 옵션을 입력하지 않은 경우 기본값은 3000 입니다.(단위: 밀리초, 기본값: 3000)

      이 옵션에 입력된 값이 클수록 웹 서버와의 네트워크 연결 상태가 좋지 않아 지연이 발생한 경우에도 분석이 정상적으로 진행됩니다. 단, 웹 서버와의 연결 끊김이 지속적으로 발생하면 분석 시간이 늘어날 가능성이 높습니다. 이 옵션에 입력된 값이 적을수록 분석 속도는 빨라지지만 웹 서버와의 네트워크 연결 상태가 좋지 않아서 지연이 발생한 경우 URL을 분석하지 못할 가능성이 있습니다.

Tip: SimpleRequestInfo 객체를 반환합니다

상태 조회

요청 상태 조회

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

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);

• ResultReader 분석 유형별 결과 읽어오기 객체
  • SastResultReader(#SastResultReader)
  • ScaResultReader(#ScaResultReader)
  • DastResultReader(#DastResultReader)

SastResultReader

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[]를 반환합니다.

ScaResultReader

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를 반환합니다.

DastResultReader

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 요청에 대한 유효성 검증에 실패한 경우 서버에서 반환되는 메시지입니다.

객체 정보

SimpleRequestInfo

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

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

SimpleAnalysisInfo

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

RequestInfo

요청에 대한 응답에 포함되는 객체입니다. 요청의 종류에 따라 SastRequestInfo, ScaRequestInfo, DastRequestInfo, StopRequestInfo 객체로 구분됩니다.

SastRequestInfo

• requestId 요청 ID
• accountId accountID
• operationType 요청 유형
  • SCAN: 분석
  • STOP: 중지
  • SBOM: SBOM 생성
• requestVersion 요청 API 버전
• stopAnalysisId 중지할 분석인 경우 분석 id
• status 요청 상태
  • ING: 진행 중
  • DONE: 완료
• result 요청 결과
  • SUCCESS: 성공
  • FAIL: 실패
• tokenId 인증 토큰의 ID
• insertTime 요청 접수 일시
• updateTime 요청 정보가 수정된 일시
• analysisList 분석 정보 목록
• requestText 사용자가 입력한 본문
• username 사용자 ID

ScaRequestInfo

• requestId 요청 ID
• accountId accountID
• operationType 요청 유형
  • SCAN: 분석
  • STOP: 중지
  • SBOM: SBOM 생성
• requestVersion 요청 API 버전
• stopAnalysisId 중지할 분석인 경우 분석 id
• status 요청 상태
  • ING: 진행 중
  • DONE: 완료
• result 요청 결과
  • SUCCESS: 성공
  • FAIL: 실패
• tokenId 인증 토큰의 ID
• insertTime 요청 접수 일시
• updateTime 요청 정보가 수정된 일시
• analysisList 분석 정보 목록
• requestText 사용자가 입력한 본문
• username 사용자 ID

DastAnalysisInfo

• requestId 요청 ID
• accountId accountID
• operationType 요청 유형
  • SCAN: 분석
  • STOP: 중지
  • SBOM: SBOM 생성
• requestVersion 요청 API 버전
• stopAnalysisId 중지할 분석의 분석 id
• status 요청 상태
  • ING: 진행 중
  • DONE: 완료
• result 요청 결과
  • SUCCESS: 성공
  • FAIL: 실패
• tokenId 인증 토큰의 ID
• insertTime 요청 접수 일시
• updateTime 요청 정보가 수정된 일시
• analysisList 분석 정보 목록 DastAnalysisInfo 객체 목록입니다.
• requestText 사용자가 입력한 본문
• username 사용자 ID

StopRequestInfo

• requestId 요청 ID
• accountId accountID
• stopAnalysisId 중지할 분석의 분석 id 중지할 분석의 id 입니다.
• status 요청 상태
  • ING: 진행 중
  • DONE: 완료
• result 요청 결과
  • SUCCESS: 성공
  • FAIL: 실패
• requestId 요청 ID
• operationType 요청 유형
  • SCAN: 분석
  • STOP: 중지
  • SBOM: SBOM 생성
• requestVersion 요청 API 버전
• insertTime 요청 접수 일시
• tokenId 인증 토큰의 ID
• updateTime 요청 정보가 수정된 일시
• requestText 사용자가 입력한 본문
• username 사용자 ID

AnalysisInfo

분석에 대한 응답에 포함되는 객체입니다. 분석의 종류에 따라 SastAnalysisInfo, ScaAnalysisInfo, DastAnalysisInfo 객체로 구분됩니다.

SastAnalysisInfo

• requestId 요청 ID
• result 분석 종료 상태
  • SUCCESS: 분석이 성공적으로 완료된 상태입니다.
  • FAIL: 분석을 올바르게 완료하지 못하고 실패한 상태입니다.
  • STOP: 중지 요청을 받아 분석이 중지된 상태입니다.
• progress 분석 진행률
• memo 메모
• startTime 분석 시작 일시
• endTime 분석 종료 일시
• issueCount 총 이슈 수
• issueCountRisk1 위험도 "매우 낮음" 이슈 수
• issueCountRisk2 위험도 "낮음" 이슈 수
• issueCountRisk3 위험도 "보통" 이슈 수
• issueCountRisk4 위험도 "높음" 이슈 수
• issueCountRisk5 위험도 "매우 높음" 이슈 수
• insertTime 분석 등록 시간
• updateTime 분석 정보 갱신 시간

ScaAnalysisInfo

• requestId 요청 ID
• result 분석 종료 상태
  • SUCCESS: 분석이 성공적으로 완료된 상태입니다.
  • FAIL: 분석을 올바르게 완료하지 못하고 실패한 상태입니다.
  • STOP: 중지 요청을 받아 분석이 중지된 상태입니다.
• progress 분석 진행률
• memo 메모
• startTime 분석 시작 일시
• endTime 분석 종료 일시
• issueCount 총 이슈 수
• issueCountRisk1 위험도 "매우 낮음" 이슈 수
• issueCountRisk2 위험도 "낮음" 이슈 수
• issueCountRisk3 위험도 "보통" 이슈 수
• issueCountRisk4 위험도 "높음" 이슈 수
• issueCountRisk5 위험도 "매우 높음" 이슈 수
• insertTime 분석 등록 시간
• updateTime 분석 정보 갱신 시간
• fileCount 분석 대상 파일 수
• cloneSize 분석 대상 크기
• componentCount 분석 대상 컴포넌트 수
• targetCount 분석 대상 수

DastAnalysisInfo

• analysisId 분석 ID
• requestId 요청 ID
• result 분석 종료 상태
  • SUCCESS: 분석이 성공적으로 완료된 상태입니다.
  • FAIL: 분석을 올바르게 완료하지 못하고 실패한 상태입니다.
  • STOP: 중지 요청을 받아 분석이 중지된 상태입니다.
• progress 분석 진행률
  • toolType 분석 유형
  • SAST: 소스코드 분석을 수행했을 때 값입니다.
  • SCA: 오픈소스 분석을 수행했을 때 값입니다.
  • DAST: 웹취약점 분석을 수행했을 때 값입니다.
• memo 메모
• startTime 분석 시작 일시
• endTime 분석 종료 일시
• issueCount 총 이슈 수
• issueCountRisk1 위험도 "매우 낮음" 이슈 수
• issueCountRisk2 위험도 "낮음" 이슈 수
• issueCountRisk3 위험도 "보통" 이슈 수
• issueCountRisk4 위험도 "높음" 이슈 수
• issueCountRisk5 위험도 "매우 높음" 이슈 수
• insertTime 분석 등록 시간
• updateTime 분석 정보 갱신 시간
• analysisType 웹취약점 분석 단계
  • RPE: 분석을 준비하는 단계입니다.
  • CRAWL: 분석 대상을 탐색하며 URL을 수집하는 단계입니다.
  • ANALYZE: 분석 대상의 취약점을 탐색하는 단계입니다.
• targetUrl 분석 대상 url
• urlCount 수집된 url 수
• requestCount 요청 횟수

---