Version: 2504.1

Tip: Sparrow On-Demand Node SDK supports TypeScript.

Requirements

Node.js 20 or higher
You must use Active LTS or Maintenance LTS releases. For details, refer to Node.js Release.

Development Environment Setup

Yarn
You can install the SDK using Yarn.

yarn add 'sparrow-ondemand-node-sdk:{latest version}'

Using Local .tgz
To use a .tgz file located locally, install it as follows:
```
yarn add ./sparrow-ondemand-node-sdk-2504.1.tgz
```

Token Issuance

Initialization

Add the following code to create an OndemandClient instance for ondemand analysis requests.

import {
    OndemandClient,
    OndemandClientConfig
} from "sparrow-ondemand-node-sdk"

// config
const config = new OndemandClientConfig({apiKey : "API_KEY"});

// create client
const OndemandClient = new OndemandClient(config);

OndemandClientConfig is used to specify configuration values when creating an OndemandClient.

apiKey : Enter the token issued in step 3 for authentication during API requests

Analysis Methods

Analysis is performed through methods of the created client. OndemandException may occur during method execution. For detailed information about exceptions, please refer to the section below.

1. Analysis Request

You can send analysis requests using the created client.

import { ScanResponse } from 'sparrow-ondemand-node-sdk';

const scanResponse: ScanResponse = await client.doAnalysis(analysisRequest);

Parameters

analysisRequest Required object
An object containing analysis request information. Functions getSastAnalysisRequest, getScaAnalysisRequest, and getDastAnalysisRequest are provided to create analysisRequest for each analysis type.
- getSastAnalysisRequest
  Creates a SastAnalysisRequest by passing analysisSource and options as arguments.
```
import {
    getSastAnalysisRequest,
    SastOption
} from "sparrow-ondemand-node-sdk"

const sastAnalysisRequest = getSastAnalysisRequest({
  analysisSource: ...,
  options : [new SastOption(...), ...]
})
```
  - analysisSource Required object
    Repository where files to be analyzed are stored, supporting VCS and ObjectStorage types.
    - Vcs
      - url Required string
        URL of the repository where files to be analyzed are stored.
      - branch string
        Name of the branch where files to be analyzed are uploaded. If not entered, the default branch is analyzed.
      - tag string
        Tag information of the branch to be analyzed.
      - commitId string
        Commit ID information to be analyzed.
      - id string
        ID for VCS authentication.
      - password string
        Password for VCS authentication. Must be entered together with id and cannot be entered at the same time as authToken.
      - authToken string
        AuthToken for VCS authentication. Cannot be entered at the same time as id and password.
    - ObjectStorage
      - bucket Required string
        Bucket of the file to be analyzed.
      - object Required string
        Object path of the file to be analyzed.
      - endPoint Required string
        Endpoint where the bucket to be analyzed is located.
      - accessKey string
        AccessKey for authentication.
      - secretKey string
        SecretKey for authentication.
  - options SastOption[ ]
    - SastOption object
      - key Required string
        SAST analysis option key
      - value Required any
        SAST analysis option value (default value exists).
- getScaAnalysisRequest
  Creates a ScaAnalysisRequest by passing analysisSource and options as arguments.
```
import {
    getScaAnalysisRequest,
    ScaOption
} from "sparrow-ondemand-node-sdk"

const scaAnalysisRequest = getScaAnalysisRequest({
  analysisSource: ...,
  options : [new ScaOption(...), ...]
})
```
  - analysisSource Required object
    Repository where files to be analyzed are stored, supporting VCS and ObjectStorage types.
    - Vcs
      - url Required string
        URL of the repository where files to be analyzed are stored.
      - branch string
        Name of the branch where files to be analyzed are uploaded. If not entered, the default branch is analyzed.
      - tag string
        Tag information of the branch to be analyzed.
      - commitId string
        Commit ID information to be analyzed.
      - id string
        ID for VCS authentication.
      - password string
        Password for VCS authentication. Must be entered together with id and cannot be entered at the same time as authToken.
      - authToken string
        AuthToken for VCS authentication. Cannot be entered at the same time as id and password.
    - ObjectStorage
      - bucket Required string
        Bucket of the file to be analyzed.
      - object Required string
        Object path of the file to be analyzed.
      - endPoint Required string
        Endpoint where the bucket to be analyzed is located.
      - accessKey string
        AccessKey for authentication.
      - secretKey string
        SecretKey for authentication.
  - options ScaOption [ ]
    - ScaOption object
      - key Required string
        SCA analysis option key
      - value Required any
        SCA analysis option value
- getDastAnalysisRequest
  Creates a DastAnalysisRequest by passing targetUrl, records, and options as arguments.
```
import {
    getDastAnalysisRequest,
    DastOption
} from "sparrow-ondemand-node-sdk"

const dastAnalysisRequest = getDastAnalysisRequest({
  targetUrl: "...",
  records: [...],
  options: [new DastOption(...), ...],
})
```
  - targetUrl Required string
    Target URL for web vulnerability analysis.
  - records string[ ]
    Login record file strings to use for web vulnerability analysis.
  - options DastOption[ ]
    - DastOptionobject
      - key Required string
        DAST analysis option key
      - value Required any
        DAST analysis option value

Return Value

ScanResponse object
- requestId number
  Analysis request ID.

Example Code

Example code for requesting SAST VCS analysis, SCA ObjectStorage analysis, and DAST analysis.

// Sast
import {
  getSastAnalysisRequest,
  VcsSource,
  SastOption,
  ScanResponse,
} from 'sparrow-ondemand-node-sdk';

const VcsSastAnalysisSource: VcsSource = {
  type: 'Vcs',
  source: {
    url: 'gitUrl',
    branch: 'branch',
    tag: 'tag',
    commitId: 'commitId',
    id: 'id',
    password: 'password',
    authToken: 'authToken',
    // Set only one of id, password or authToken
  },
};

const sastOption = new SastOption('extensions', ['*']);

const sastAnalysisRequest = getSastAnalysisRequest({
  analysisSource: VcsSastAnalysisSource,
  options: [sastOption],
});

const scanResponse: ScanResponse = await client.doAnalysis(sastAnalysisRequest);

//Sca
import {
  getScaAnalysisRequest,
  ObjectStorageSource,
  ScaOption,
  ScanResponse,
} from 'sparrow-ondemand-node-sdk';

const ObjectStorageAnalysisSource: ObjectStorageSource = {
  type: 'ObjectStorage',
  source: {
    bucket: 'bucket',
    object: 'object',
    endPoint: 'https://s3.ap-northeast-2.amazonaws.com',
    accessKey: 'accessKey',
    secretKey: 'secretKey',
  },
};

const scaOption = new ScaOption('extensions', ['*']);

const scaAnalysisRequest = getScaAnalysisRequest({
  analysisSource: ObjectStorageAnalysisSource,
  options: [scaOption],
});

const scanResponse: ScanResponse = await client.doAnalysis(scaAnalysisRequest);

//Dast
import {
  getDastAnalysisRequest,
  DastOption,
  ScanResponse,
} from 'sparrow-ondemand-node-sdk';

const dastOption = new DastOption('crawler.target.contain_entire_seed', true);

const dastRequest = getDastAnalysisRequest({
  targetUrl: 'testURL',
  records: ['record'],
  options: [dastOption],
});

const scanResponse: ScanResponse = await client.doAnalysis(dastAnalysisRequest);

Call the doAnalysis method with each tool's AnalysisRequest as a parameter.
You can check the requestId from the ScanResponse response.

2. Analysis Status Check

If the analysis request was successful, you can check the status of the ongoing analysis.

import { AnalysisStatus } from 'sparrow-ondemand-node-sdk';

const analysisStatus: AnalysisStatus =
  await client.getAnalysisStatus(requestId);

Parameters

requestId Required number
Analysis request ID.

Return Value

Analysis object
- requestId number Analysis request ID
- index number
  Analysis index when requested
- status string
  Analysis status
- result string
  Analysis result
- progress number
  Analysis progress rate
- toolType string
  Analysis type
- startTime string Analysis start time
- endTime string Analysis end time
- issueCount number
  Total number of issues detected in the analysis
- issueCountRisk1 number
  Number of issues with 'Low' risk level
- issueCountRisk2 number
  Number of issues with 'Medium' risk level
- issueCountRisk3 number
  Number of issues with 'High' risk level
- issueCountRisk4 number
  Number of issues with 'Critical' risk level
- issueCountRisk5 number
  Number of issues with 'Very Critical' risk level
- resultSchemaVersion string
  Analysis result format version

Example Code

import { AnalysisStatus } from 'sparrow-ondemand-node-sdk';

let analysisStatusResponse = null;

while (true) {
  analysisStatusResponse = await client.getAnalysisStatus(
    analysisRequestResponse.requestId,
  );
  if (analysisStatusResponse.result === null) {
    console.log('Analysis in progress');
    // Wait 20 seconds
    await new Promise((resolve) => setTimeout(resolve, 20000));
  } else {
    console.log('Analysis completed', analysisStatusResponse);
    break;
  }
}

3. Analysis Result Download

If analysis is completed, you can download the analysis result file.

await client.downloadAnalysisResult({
  requestId,
  index,
  filePath,
});

When you call the downloadAnalysisResult method, the analysis result file is downloaded to the specified file path.

Parameters

requestId Required number
Analysis request ID.
index Required number
Analysis list index at the time of analysis
filePath Required string
File path for analysis download. The path must include the file name and only zip extension is supported.
ex) /home/result.zip

Return Value

Promise<void>

4. Stop Analysis

You can stop an ongoing analysis.

await client.stopAnalysis(requestId);

Parameters

requestId Required number
Analysis request ID.

Return Value

Promise<void>

OndemandException

OndemandException delivers exceptions through RuntimeException and is classified into two types.

OndmandClientException
May occur when the client sends a request to Sparrow On-Demand or processes a response from Sparrow On-Demand.
- resultCode string
  Contains code information about the cause of the exception.
- message string
  Contains a message about the exception.
OndmandServerException
Occurs when Sparrow On-Demand successfully receives a request but cannot process it.
- resultCode string
  Contains code information about the cause of the exception.
- message string
  Contains a message about the exception.
- statusCode number
  Indicates the response status code.
- errors any[ ]
  A detailed failure message returned from the server when request validation fails.

ANALYSIS_STATUS

Indicates analysis status and is divided into 7 types.

INIT
Indicates that initialization is in progress to perform analysis.
READY
Indicates that analysis preparation is in progress after initialization is complete.
PRE_PROCESS
Indicates that preprocessing for analysis is in progress.
ANALYSIS
Indicates that analysis is in progress.
POST_PROCESS
Indicates that result processing is in progress after analysis completion.
COMPLETE
Indicates that both analysis and result processing are complete.
STOP
Indicates that analysis has been stopped.

ANALYSIS_RESULT

Indicates the analysis result value.

SUCCESS
Indicates that analysis was successful.
FAIL
Indicates that analysis failed.
STOPPED Indicates that analysis was stopped.

Development Environment Setup

Token Issuance

Initialization

Analysis Methods

1. Analysis Request​

Parameters​

Return Value​

Example Code​

2. Analysis Status Check​

Parameters​

Return Value​

3. Analysis Result Download​

Parameters​

Return Value​

4. Stop Analysis​

Parameters​

Return Value​

OndemandException​

ANALYSIS_STATUS​

ANALYSIS_RESULT​

1. Analysis Request

Parameters

Return Value

Example Code

2. Analysis Status Check

Parameters

Return Value

3. Analysis Result Download

Parameters

Return Value

4. Stop Analysis

Parameters

Return Value

OndemandException

ANALYSIS_STATUS

ANALYSIS_RESULT