Skip to main content
Version: 2608.1

Sparrow On-Demand Node SDK

With the Node SDK you can easily run source code analysis, open source analysis, and web vulnerability analysis without calling the Sparrow On-Demand API directly. Use the Node SDK provided by Sparrow OnDemand to integrate the solution into your software development process.

Tip: The Sparrow On-Demand Node SDK supports TypeScript.


Environment setup​

  • Install Node 20 or later

  • npm configuration

    npm install @sparrowai/ondemand-node-sdk

  • A Sparrow On-Demand API token is required

    Tip: See Token issuance.


Initialization​

Create the client object OndemandNodeClient that will call the API. You can specify configuration values with 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 The token (API_KEY) issued by Sparrow On-Demand and used for authentication in API requests.

Analysis request​

Common method​

The Node SDK provides the following method per analysis type, such as source code analysis, open source analysis, and web vulnerability analysis.

const requestInfo = await client.doAnalysis(analysisRequest);

Source code analysis​

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

const sastVcsRequest = getSastAnalysisRequest({
  analysisSource: {
    type: ANALYSIS_SOURCE_TYPE.VCS,
    source: {
      url: 'github_url',
      branch: 'branch_name',
      authToken: 'auth_token',
    },
  }
  options: {
    extensions: ['java'],
    issueSimilarity: true,
  },
  callbacks: [
    {
      url: 'callback_url',
      type : ['ANALYSIS_PROGRESS'],
      headers: [
        { key: 'key1', value: 'value1' },
        { key: 'key2', value: 'value2' },
        { key: 'key3', value: 'value3' }
      ]
    },
  ],
})

const requestInfo = await client.doAnalysis(sastVcsRequest);

getSastAnalysisRequest The source code analysis request method

  • callbacks Callback list List

    A callback is a webhook callback that you can receive after calling the analysis request API, when a specific event completes as the analysis you requested progresses. Enter callbacks to receive information about the progress of the analysis you started.

    For the callback list, you can use the of method to configure the callback list with the CallbackType and CallbackHeader classes, or you can set the callback-format classes SrcUploadCallback, CompleteCallback, ProgressCallback, and DastProgressCallback instead of a callback list.

    • SrcUploadCallback: source upload callback
    • CompleteCallback : completion callback
    • ProgressCallback : progress callback
    • DastProgressCallback : web vulnerability analysis progress callback

  • sastOptions Source code analysis options Options related to source code analysis.

    • analysisSource Analysis target Information about the analysis target. For source code analysis or open source analysis, you can analyze source located in a VCS or in object storage.

      • url VCS URL Required String The URL (VCS_URL) of the repository where the files to be analyzed are stored. If you enter only this value, the files in the latest commit of the branch set as the default in the Git repository are analyzed.

        Tip: If you enter only url, the files in the latest commit of the branch set as the default in the Git repository are analyzed.

      • branch Branch String

      • commitId Commit ID String

      • tag Tag String

      • id VCS ID String

      • password VCS password String

      • authToken VCS token String

        Tip: These are the credentials for the VCS repository. You must enter them when authentication is required to access the repository. You use either password or authToken.

      • endPoint Storage endpoint Required String

      • bucket Storage bucket Required String

      • object Storage object name Required String

      • accessKey Storage access key String

      • secretKey Storage secret key String

    • extensions List of file extensions to analyze Source code analysis distinguishes the files to include in the analysis target by extension (FILE_EXTENSION1, FILE_EXTENSION2). Files that do not match are excluded from the analysis. If you enter *, all files are analyzed.

      Input examples

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

      Tip: For an archive file, if the extension of the archive file is part of the analysis target, all files inside the archive are included in the analysis.

    • excludedPath Paths excluded from analysis If there are files you want to exclude from the analysis, enter the paths of those files (EXCLUDED_PATH1, EXCLUDED_PATH2, EXCLUDED_PATH3). No issues are detected from files under the paths entered here.

      Input examples

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

      Tip: Matching is case-insensitive and you can use *.

      • *AA*: matches any string containing AA
      • AA* : matches any string starting with AA If you want to set the excluded paths another way, see below.

    • maxSourceSize Maximum source size integer The maximum size of the analysis target to be inspected in source code analysis or open source analysis. If the size of the analysis target downloaded while source code analysis or open source analysis is running is larger than SOURCE_SIZE, the analysis ends. You can enter an integer between 1 and 200. (Unit: MB)

Tip: Returns a SimpleRequestInfo object.


Open source analysis​

import { getScaAnalysisRequest } from "@sparrowai/ondemand-node-sdk";
import { ANALYSIS_SOURCE_TYPE, SCA_TARGET } from "@sparrowai/ondemand-node-sdk/types"

const scaObjectStorageRequest = getScaAnalysisRequest({
  analysisSource: {
    type: ANALYSIS_SOURCE_TYPE.OBJECT_STORAGE,
    source: {
      bucket: 'bucket',
      object: 'object',
      endPoint: 'endPoint',
      accessKey: 'accessKey',
      secretKey: 'secretKey',
    },
  }
  options: {
    targetType : SCA_TARGET.SBOM,
    sbomCreatorEmail : 'email'
  },
  callbacks: [
    {
      url: 'callback_url',
      type : ['ANALYSIS_PROGRESS'],
      headers: [
        { key: 'key1', value: 'value1' },
        { key: 'key2', value: 'value2' },
        { key: 'key3', value: 'value3' }
      ]
    },
  ],
})

const requestInfo = await client.doAnalysis(scaObjectStorageRequest);

getScaAnalysisRequest The open source analysis request method

  • callbacks Callback list List

    A callback is a webhook callback that you can receive after calling the analysis request API, when a specific event completes as the analysis you requested progresses. Enter callbacks to receive information about the progress of the analysis you started.

    For the callback list, you can use the of method to configure the callback list with the CallbackType and CallbackHeader classes, or you can set the callback-format classes SrcUploadCallback, CompleteCallback, ProgressCallback, and DastProgressCallback instead of a callback list.

    • SrcUploadCallback: source upload callback
    • CompleteCallback : completion callback
    • ProgressCallback : progress callback
    • DastProgressCallback : web vulnerability analysis progress callback

  • scaOptions Open source analysis options Options related to open source analysis.

    • targetType Open source analysis target type The type of the open source analysis target. If you do not enter a value, the default is FILE.

      • FILE : file analysis
      • SBOM : SBOM analysis

      Tip: For SBOM file analysis, up to 100 files that match an SBOM standard format can be analyzed among the analysis targets. The extensions that can be analyzed are .json, .spdx, .xml, .yaml, and .zip; a zip file is treated as an SBOM in SWID tag format. When you run an SBOM file analysis, a new SBOM cannot be generated.

    • analysisSource Analysis target Information about the analysis target. For source code analysis or open source analysis, you can analyze source located in a VCS or in object storage.

      • url VCS URL Required String The URL (VCS_URL) of the repository where the files to be analyzed are stored. If you enter only this value, the files in the latest commit of the branch set as the default in the Git repository are analyzed.

        Tip: If you enter only url, the files in the latest commit of the branch set as the default in the Git repository are analyzed.

      • branch Branch String

      • commitId Commit ID String

      • tag Tag String

      • id VCS ID String

      • password VCS password String

      • authToken VCS token String

        Tip: These are the credentials for the VCS repository. You must enter them when authentication is required to access the repository. You use either password or authToken.

      • endPoint Storage endpoint Required String

      • bucket Storage bucket Required String

      • object Storage object name Required String

      • accessKey Storage access key String

      • secretKey Storage secret key String

    • excludedPath Paths excluded from analysis If there are files you want to exclude from the analysis, enter the paths of those files (EXCLUDED_PATH1, EXCLUDED_PATH2, EXCLUDED_PATH3). No issues are detected from files under the paths entered here.

      Input examples

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

      Tip: Matching is case-insensitive and you can use *.

      • *AA*: matches any string containing AA
      • AA* : matches any string starting with AA If you want to set the excluded paths another way, see below.

    • maxSourceSize Maximum source size integer The maximum size of the analysis target to be inspected in source code analysis or open source analysis. If the size of the analysis target downloaded while source code analysis or open source analysis is running is larger than SOURCE_SIZE, the analysis ends. You can enter an integer between 1 and 200. (Unit: MB)

    • sbomTypes SBOM type list The SBOM types you want to receive. If the list is empty, no SBOM is generated. You can enter the following values.

      • 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 creator string

    • sbomCreatorEmail SBOM creator email string

Tip: Returns a SimpleRequestInfo object.


Web vulnerability analysis​

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

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

getDastAnalysisRequest The web vulnerability analysis request method

  • callbacks Callback list List

    A callback is a webhook callback that you can receive after calling the analysis request API, when a specific event completes as the analysis you requested progresses. Enter callbacks to receive information about the progress of the analysis you started.

    For the callback list, you can use the of method to configure the callback list with the CallbackType and CallbackHeader classes, or you can set the callback-format classes SrcUploadCallback, CompleteCallback, ProgressCallback, and DastProgressCallback instead of a callback list.

    • SrcUploadCallback: source upload callback
    • CompleteCallback : completion callback
    • ProgressCallback : progress callback
    • DastProgressCallback : web vulnerability analysis progress callback

  • dastOptions Web vulnerability analysis options Options related to web vulnerability analysis.

    • crawlerTargetSeedUrls Analysis target URL Required String The URL to be analyzed; only one can be entered.

    When you enter the analysis target URL, you must confirm that the URL is reachable from the external internet and that no firewall is active on that server.

    • commonRecordsLogin Login record file string A login record file is a file in .ecl format saved from the Event Clipboard that records the user's actions on a specific URL. It is mainly used when crawling or analyzing URLs, by storing the ID and password information the user used to log in on a specific URL.

    When you attach a login record file, if the crawler or analyzer reaches the URL at which the Event Clipboard recording started, the user actions stored in that file are replayed exactly. This lets you pass the authentication required on a login page.

    • Download the Sparrow Event Clipboard, save your login procedure as a file, and use it.

    • crawlerTargetContainEntireSeed Crawl sub-paths only boolean Crawl sub-paths only indicates whether to crawl only the paths that contain the entire analysis target URL entered in the project, and is distinguished by true or false.(Default: true) If you set this option to true, only the sub-paths that include the analysis target URL are analyzed. If you set this option to false, the parent paths that contain the project's analysis target URL are also analyzed.

    • crawlerRequestAcceptLanguage Client language Sets the language configured in the browser in which the web application under analysis is displayed, and which languages the HTTP client can understand. You can enter it in the locale format shown as language.(Default: ko)

      Tip: Enter it in a format such as ko.

    • crawlerCrawlMaxUrl Maximum number of crawled URLs integer The maximum number of crawled URLs is the maximum number of URLs that can be crawled in the analysis. If too many URLs are crawled, the analysis results may not be accurate. It is therefore a good idea to specify the maximum number of URLs to crawl in this option.(Default: 0)

      The larger the value entered in this option, the more URLs can be crawled, but the analysis time required for crawling can also increase. The smaller the value entered, the fewer URLs can be crawled and the shorter the analysis time. If you enter nothing, the default value of the option is 0, in which case the number of URLs that can be crawled is not limited.

    • crawlerCrawlTimeout Maximum crawl time integer

      The maximum crawl time is the maximum amount of time URLs can be crawled in the analysis. If it takes too much time, the analysis results may not be accurate. It is therefore a good idea to specify the crawl time in this option.(Unit: minutes, default: 0)

      The larger the value entered in this option, the longer the analysis time for crawling and the more URLs that can be crawled. The smaller the value entered, the shorter the analysis time and the fewer URLs that can be crawled. If you enter nothing, the default value of the option is 0, in which case the crawl time is not limited.

    • analyzerAnalyzeTimeout Maximum analysis time integer

      The maximum analysis time is the maximum amount of time URLs can be analyzed in the analysis. If it takes too much time, the analysis results may not be accurate. It is therefore a good idea to specify the analysis time in this option.(Unit: minutes, default: 0)

      The larger the value entered in this option, the longer the analysis time and the more analysis results. The smaller the value entered, the shorter the analysis time and the fewer analysis results. If you enter nothing, the default value of the option is 0, in which case the analysis time is not limited.

    • crawlerSkipUrl URLs excluded from crawling string The maximum analysis time is the maximum amount of time URLs can be analyzed in the analysis. If it takes too much time, the analysis results may not be accurate. It is therefore a good idea to specify the analysis time in this option.(Unit: minutes, default: 0)

      The larger the value entered in this option, the longer the analysis time and the more analysis results. The smaller the value entered, the shorter the analysis time and the fewer analysis results. If you enter nothing, the default value of the option is 0, in which case the analysis time is not limited.

    • analyzerSkipUrl URLs excluded from analysis string

      URLs excluded from analysis refers to a list of strings such that, if a URL contains a specific word, that URL is skipped and not analyzed. You can enter one or more URLs, separated by Enter or a comma (,).

      If even one of the words in the list entered in this option is contained in a URL to be analyzed, that URL is not analyzed.

      Tip: If you want to exclude an action on a page from the analysis rather than the entire page shown by the URL, use the Elements excluded from event execution option below.

    • crawlerSkipUrlSuffix Excluded URL suffixes string

      Excluded URL suffixes refers to a list of suffixes such that, if a specific word or extension appears at the end of a URL, that URL is skipped and not crawled. Enter them in the extension format beginning with a period (.), separated by Enter or a comma (,).(Default: .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`) If even one of the words in the list entered in this option appears at the end of a URL to be crawled, that URL is not crawled. Because the URL is skipped based on HTML element attribute values and the like before navigating to it, that URL is not visited, so it can be skipped before actions such as file downloads are performed.

    • crawlerExcludeCssSelector Elements excluded from event execution (CSS selector)

      Elements excluded from event execution (CSS selector) is a list of CSS selectors representing the HTML elements to be excluded, so that the browser does not fire events on them during URL crawling. Enter one or more values as strings, separated by Enter or a comma (,).

      If even one of the CSS selectors in the list entered in this option is present on the page, no events are fired on the matching HTML element or any of its child HTML elements. This lets you configure the crawler not to click the logout button on a page.

    • crawlerIncludeCssSelector Additional elements for event execution (CSS selector)

      Additional elements for event execution (CSS selector) is a list of CSS selectors representing the HTML elements on which events are fired unconditionally during URL crawling, even if they are not among the HTML elements that normally support event execution. Enter one or more values as strings, separated by Enter or a comma (,).

      If even one of the CSS selectors in the list entered in this option is present on the page, all events on the matching HTML element and its child HTML elements are fired. This lets you fire events on elements such as tags that are not normally included in event execution on a page.

    • crawlerExcludeXpath Elements excluded from event execution (XPath)

      Elements excluded from event execution (XPath) is a list of XPaths representing the HTML elements to be excluded, so that the browser does not fire events on them during URL crawling. Enter one or more values as strings, separated by Enter or a comma (,).

      If even one of the XPaths in the list entered in this option is present on the page, no events are fired on the matching HTML element or any of its child HTML elements. This lets you configure the crawler not to click the logout button on a page.

    • crawlerIncludeXpath Additional elements for event execution (XPath)

      Additional elements for event execution (XPath) is a list of XPaths representing the HTML elements on which events are fired unconditionally during URL crawling, even if they are not among the HTML elements that normally support event execution. Enter one or more values as strings, separated by Enter or a comma (,).

      If even one of the XPaths in the list entered in this option is present on the page, all events on the matching HTML element and its child HTML elements are fired. This lets you fire events on elements such as tags that are not normally included in event execution on a page.

    • crawlerRequestCustomHeaders Custom HTTP headers

      Custom HTTP headers refers to the list of header names and values included in the HTTP requests sent when crawling URLs. If you enter a header name and value in this option, that header is added to every HTTP request message. Click the Add button to add one or more headers, and click the trash icon to delete them.

      In this option you must enter the headers that are strictly required for the HTTP request. Because this configures a proxy in the browser, crawling may become slower.

      Except for the Cookie header, if you enter several headers with the same name, only one of them is applied. Therefore, if you need to enter multiple values, separate the header values with ;. If a header with the same name already exists, that header is removed and the custom header is added. To use custom headers, the host of the analysis target URL must not be set to localhost or 127.0.0.1. If you want to analyze a web application running locally, you must enter the local IP address.

    • crawlerLimitUrlDepthDegree URL crawl depth

      URL crawl depth means how far the URLs to be crawled are from the start URL, and is distinguished as high, medium, or low. The farther a URL is, the more minimum actions, such as page navigations, are required to reach that URL from the start URL.(Default: medium)

      If you set this option to high, URLs far from the start URL are also crawled, but crawling takes longer. If you set this option to low, the time spent crawling URLs in the project is shorter, but URLs that are far away are not crawled.

    • crawlerLimitDomDepthDegree DOM crawl depth

      DOM crawl depth means how far the DOMs to be crawled are from the first DOM created at the same URL, and is distinguished as high, medium, or low. The farther a DOM is, the more minimum actions are required to reach that particular DOM of the same URL from the first DOM.(Default: medium)

      If you set this option to high, DOMs far from the first DOM created when navigating to the URL are also crawled, but crawling takes longer. If you set this option to low, the time spent crawling DOMs in the project is shorter, but DOMs that are far away are not crawled.

    • crawlerBrowserExplicitTimeout Event wait time integer

      Event wait time refers to the time to wait for the result of each event execution to be reflected in the DOM. You can enter a number from 0 to 5000; if you do not enter the option, the default is 300.(Unit: milliseconds, default: 300)

      The larger the value entered in this option, the more you can crawl URLs of web applications that take time to reflect executed events in the DOM, but the slower the crawling. The smaller the value entered, the faster URLs are crawled, but URLs of web applications that need time when the DOM changes are not crawled.

    • crawlerRequestCountPerSecond Number of HTTP requests integer

      Number of HTTP requests refers to the number of HTTP requests that can be sent per second when crawling URLs. You can enter a number from -1 to 10000; if you do not enter the option, the default is -1, in which case the number of HTTP requests that can be sent is not limited.(Unit: count, default: -1)

      The larger the value entered in this option, the more HTTP requests can be sent per second and the faster URLs are crawled, but the traffic volume increases, which can increase the load on the web application server being analyzed. The smaller the value entered, the lower the traffic volume and the lower the load on the web application server being analyzed, but the slower URLs are crawled.

    • crawlerClientTimeout HTTP client wait time integer HTTP client wait time refers to the maximum time to wait when a delay occurs while the HTTP client connects to the web server to perform the analysis, sends the HTTP request, and receives the HTTP response. You can enter a number from 0 to 30000; if you do not enter the option, the default is 3000.(Unit: milliseconds, default: 3000)

      The larger the value entered in this option, the more the analysis proceeds normally even when a delay occurs because the network connection to the web server is poor. Note, however, that if disconnections from the web server occur continuously, the analysis time is likely to increase. The smaller the value entered in this option, the faster the analysis, but there is a greater chance that a URL cannot be analyzed if a delay occurs because the network connection to the web server is poor.

Tip: Returns a SimpleRequestInfo object


Status inquiry​

Request status inquiry​

After requesting an analysis, you can check the request status.

const requestInfo = await client.getRequest(requestId: number)
  • requestId Request ID Required number

Tip: Returns a RequestInfo object.


Analysis status inquiry​

After the analysis has started, you can check the analysis status using the analysis ID.

const analysisInfo = await client.getAnalysis(analysisId: number)
  • analysisId Analysis ID Required number

Tip: Returns an AnalysisInfo object.


Download result file​

After the analysis is complete, you can download the analysis results as a file.

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

  • analysisId Analysis ID Required number

  • filePath Download path Required string

    Tip : For the download path, enter a file name that includes the zip extension. /home/result.zip


Reading the analysis results​

Once the analysis is complete, you can download the result file, extract it, and then read the results through the Reader object for each tool.

Common method​

const resultReader = client.getAnalysiResultReader<T extends ResultReader>(analysisId: number ,filePath: string);
  • ResultReader The result reader object for each analysis type
    • SastResultReader(#SastResultReader)
    • ScaResultReader(#ScaResultReader)
    • DastResultReader(#DastResultReader)

SastResultReader​

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

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

// 2. Read the analysis result summary 
const sastSummary : SastSummary = sastResultReader.readSummary();

// 3. Read the analysis asset list
const assets : string[] = sastResultReader.readAsset();

// 4. Return the number of issue files
const size : number = sastResultReader.issueSize();

// 5. Return the SastIssue list from an issue file
const sastIssues : SastIssue[] = sastResultReader.readIssue(index: number);

// 6. Return the WorkMessage list from the work messages
const workMessages : WorkMessage[] = sastResultReader.readWorkMessage();

  • SastResultReader

    • analysisId Analysis ID Required number
    • filePath Download path Required string

  • readSummary The method that reads the analysis result summary

  • readAsset The method that reads the analysis asset list

    Tip: Returns string[].

  • issueSize The method that returns the number of issue files

    Tip: Returns number.

  • readIssue The method that returns the SastIssue list

    • index

      Tip: Returns SastIssue[]; the maximum value can be checked with the issueSize() method.

  • readWorkMessage The method that returns the WorkMessage list

    Tip: Returns WorkMessage[].


ScaResultReader​

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

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

// 2. Read the analysis result summary 
const scaSummary : ScaSummary = scaResultReader.readSummary();

// 3. Read the analysis asset list
const assets : string[] = scaResultReader.readAsset();

// 4. Return the number of issue files
const size : number = scaResultReader.issueSize();

// 5. Return the SastIssue list from an issue file
const scaComponents : ScaComponent[] = scaResultReader.readIssue(index: number);

// 6. Return the WorkMessage list from the work messages
const workMessages : WorkMessage[] = scaResultReader.readWorkMessage();

// 7. Return the SBOM file path
const sbomPath : string = scaResultReader.getSbomPath(sbomType: SbomType);
// ex. const sbomPath : string = scaResultReader.getSbomPath(SbomType.SPDX22);

// 8. Return the license notice file (HTML) path
const path : string = scaResultReader.getLicenseNoticeHtmlPath();

// 9. Return the license notice file (Markdown) path
const path : string = scaResultReader.getLicenseNoticeMarkDownPath();

// 10. Return the license notice file (Text) path
const path : string = scaResultReader.getLicenseNoticeTextPath();

  • SastResultReader

    • analysisId Analysis ID Required number
    • filePath Download path Required string

  • readSummary The method that reads the analysis result summary

  • readAsset The method that reads the analysis asset list

    Tip: Returns string[].

  • issueSize The method that returns the number of issue files

    Tip: Returns number.

  • readIssue The method that returns the SastIssue list

    • index

      Tip: Returns SastIssue[]; the maximum value can be checked with the issueSize() method.

  • readWorkMessage The method that returns the WorkMessage list

    Tip: Returns WorkMessage[].

  • getSbomPath The method that returns the SBOM file path

    • sbomType SBOM type Required

    Tip: Returns the SBOM file path sbomPath.

  • getLicenseNoticeHtmlPath The method that returns the license notice file (HTML) path

    Tip: Returns the license notice file path path.

  • getLicenseNoticeMarkDownPath The method that returns the license notice file (Markdown) path

    Tip: Returns the license notice file path path.

  • getLicenseNoticeTextPath The method that returns the license notice file (Text) path

    Tip: Returns the license notice file path path.


DastResultReader​

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

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

// 2. Read the analysis result summary 
const dastSummary : DastSummary = dastResultReader.readSummary();

// 3. Read the analysis asset list
const assets : string[] = dastResultReader.readAsset();

// 4. Return the number of issue files
const size : number = dastResultReader.issueSize();

// 5. Return the SastIssue list from an issue file
const dastIssues : DastIssue[] = dastResultReader.readIssue(index: number);

// 6. Return the WorkMessage list from the work messages
const workMessages : WorkMessage[] = dastResultReader.readWorkMessage();

  • SastResultReader

    • analysisId Analysis ID Required number
    • filePath Download path Required string

  • readSummary The method that reads the analysis result summary

  • readAsset The method that reads the analysis asset list

    Tip: Returns string[].

  • issueSize The method that returns the number of issue files

    Tip: Returns number.

  • readIssue The method that returns the SastIssue list

    • index

      Tip: Returns SastIssue[]; the maximum value can be checked with the issueSize() method.

  • readWorkMessage The method that returns the WorkMessage list

    Tip: Returns WorkMessage[].


Stop analysis​

You can stop an analysis that is in progress.

await client.stopAnalysis(analysisId: number);
  • analysisId Analysis ID Required number

Tip: Returns nothing.


Exception handling​

You can run analyses by calling methods on the OndemandNodeClient instance created in Initialization. If an OndemandException occurs while a method runs, see below for its meaning and how to handle it. OndemandException delivers the exception through RuntimeException and is classified into two types.

  • OndmandClientException Can occur when the client sends a request to Sparrow On-Demand or when it processes a response from Sparrow On-Demand.
    • resultCode Result code string The code DATA_PARSING_FAIL is shown.
    • message Message string A message about the cause of the exception.
  • OndmandServerException Occurs when Sparrow On-Demand received the request successfully but could not process it.
    • resultCode Result code string A different code is shown depending on the cause of the exception. For details, see API result codes.
    • message Message string A message about the cause of the exception.
    • statusCode Status code number Indicates the response status code.
    • validationErrors Validation error message string The message returned by the server when validation of the request fails.

Object information​

SimpleRequestInfo​

  • requestId Request ID Long
  • result Request result String The result with which the analysis ended. It takes one of the following values.
    • SUCCESS: the analysis completed successfully
    • FAIL: the analysis did not complete correctly and failed
    • STOP: the analysis was stopped after a stop request
  • analysisList Analysis list List

    Tip: A list of SimpleAnalysisInfo objects.


SimpleAnalysisInfo​

  • analysisId Analysis ID Long
  • requestId Request ID integer
  • status Analysis status String
    The status according to the phase the analysis is in. It is shown as one of the following.
    • STOP_PROCESS: stopping the analysis after receiving a stop request
    • INIT : preparing the environment to run the analysis
    • READY: the environment is configured and the analysis target is being prepared
    • PRE_PROCESS: pre-processing the analysis target for the analysis
    • ANALYSIS: the analysis is running
    • POST_PROCESS: the analysis has finished and the results are being processed
    • COMPLETE: the analysis has ended
  • toolType Analysis type String
  • memo Memo String

RequestInfo​

The object included in the response about a request. Depending on the type of request, it is one of the SastRequestInfo, ScaRequestInfo, DastRequestInfo, or StopRequestInfo objects.

SastRequestInfo​

  • requestId Request ID
  • accountId accountID
  • operationType Request type
    • SCAN: analysis
    • STOP: stop
    • SBOM: SBOM generation
  • requestVersion Request API version
  • stopAnalysisId The analysis id, if this is an analysis to be stopped
  • status Request status
    • ING: in progress
    • DONE: complete
  • result Request result
    • SUCCESS: success
    • FAIL: failure
  • tokenId ID of the authentication token
  • insertTime Request received timestamp
  • updateTime Timestamp when the request information was modified
  • analysisList Analysis information list
  • requestText Body entered by the user
  • username User ID

ScaRequestInfo​

  • requestId Request ID
  • accountId accountID
  • operationType Request type
    • SCAN: analysis
    • STOP: stop
    • SBOM: SBOM generation
  • requestVersion Request API version
  • stopAnalysisId The analysis id, if this is an analysis to be stopped
  • status Request status
    • ING: in progress
    • DONE: complete
  • result Request result
    • SUCCESS: success
    • FAIL: failure
  • tokenId ID of the authentication token
  • insertTime Request received timestamp
  • updateTime Timestamp when the request information was modified
  • analysisList Analysis information list
  • requestText Body entered by the user
  • username User ID

DastAnalysisInfo​

  • requestId Request ID
  • accountId accountID
  • operationType Request type
    • SCAN: analysis
    • STOP: stop
    • SBOM: SBOM generation
  • requestVersion Request API version
  • stopAnalysisId Analysis id of the analysis to be stopped
  • status Request status
    • ING: in progress
    • DONE: complete
  • result Request result
    • SUCCESS: success
    • FAIL: failure
  • tokenId ID of the authentication token
  • insertTime Request received timestamp
  • updateTime Timestamp when the request information was modified
  • analysisList Analysis information list A list of DastAnalysisInfo objects.
  • requestText Body entered by the user
  • username User ID

StopRequestInfo​

  • requestId Request ID
  • accountId accountID
  • stopAnalysisId Analysis id of the analysis to be stopped The id of the analysis to be stopped.
  • status Request status
    • ING: in progress
    • DONE: complete
  • result Request result
    • SUCCESS: success
    • FAIL: failure
  • requestId Request ID
  • operationType Request type
    • SCAN: analysis
    • STOP: stop
    • SBOM: SBOM generation
  • requestVersion Request API version
  • insertTime Request received timestamp
  • tokenId ID of the authentication token
  • updateTime Timestamp when the request information was modified
  • requestText Body entered by the user
  • username User ID

AnalysisInfo​

The object included in the response about an analysis. Depending on the type of analysis, it is one of the SastAnalysisInfo, ScaAnalysisInfo, or DastAnalysisInfo objects.

SastAnalysisInfo​

  • requestId Request ID
  • result Analysis completion status
    • SUCCESS: the analysis completed successfully.
    • FAIL: the analysis did not complete correctly and failed.
    • STOP: the analysis was stopped after a stop request.
  • progress Analysis progress
  • memo Memo
  • startTime Analysis start timestamp
  • endTime Analysis end timestamp
  • issueCount Total number of issues
  • issueCountRisk1 Number of issues with risk level "Very low"
  • issueCountRisk2 Number of issues with risk level "Low"
  • issueCountRisk3 Number of issues with risk level "Medium"
  • issueCountRisk4 Number of issues with risk level "High"
  • issueCountRisk5 Number of issues with risk level "Very high"
  • insertTime Analysis registration time
  • updateTime Analysis information update time

ScaAnalysisInfo​

  • requestId Request ID
  • result Analysis completion status
    • SUCCESS: the analysis completed successfully.
    • FAIL: the analysis did not complete correctly and failed.
    • STOP: the analysis was stopped after a stop request.
  • progress Analysis progress
  • memo Memo
  • startTime Analysis start timestamp
  • endTime Analysis end timestamp
  • issueCount Total number of issues
  • issueCountRisk1 Number of issues with risk level "Very low"
  • issueCountRisk2 Number of issues with risk level "Low"
  • issueCountRisk3 Number of issues with risk level "Medium"
  • issueCountRisk4 Number of issues with risk level "High"
  • issueCountRisk5 Number of issues with risk level "Very high"
  • insertTime Analysis registration time
  • updateTime Analysis information update time
  • fileCount Number of analyzed files
  • cloneSize Analysis target size
  • componentCount Number of components in the analysis target
  • targetCount Number of analysis targets

DastAnalysisInfo​

  • analysisId Analysis ID
  • requestId Request ID
  • result Analysis completion status
    • SUCCESS: the analysis completed successfully.
    • FAIL: the analysis did not complete correctly and failed.
    • STOP: the analysis was stopped after a stop request.
  • progress Analysis progress
    • toolType Analysis type
    • SAST: the value when a source code analysis was performed.
    • SCA: the value when an open source analysis was performed.
    • DAST: the value when a web vulnerability analysis was performed.
  • memo Memo
  • startTime Analysis start timestamp
  • endTime Analysis end timestamp
  • issueCount Total number of issues
  • issueCountRisk1 Number of issues with risk level "Very low"
  • issueCountRisk2 Number of issues with risk level "Low"
  • issueCountRisk3 Number of issues with risk level "Medium"
  • issueCountRisk4 Number of issues with risk level "High"
  • issueCountRisk5 Number of issues with risk level "Very high"
  • insertTime Analysis registration time
  • updateTime Analysis information update time
  • analysisType Web vulnerability analysis phase
    • RPE: the phase in which the analysis is prepared.
    • CRAWL: the phase in which the analysis target is explored and URLs are crawled.
    • ANALYZE: the phase in which vulnerabilities in the analysis target are explored.
  • targetUrl Analysis target url
  • urlCount Number of crawled urls
  • requestCount Number of requests