Requirements

• JDK 17 or higher

Development Environment Setup

• Using Maven Repository
  You can use the SDK using Maven Repository. Add it to your gradle script as follows.

  implementation 'com.sparrow.ondemand:sparrow-ondemand-java-sdk:1.0.0'

• Using Local JAR
  To use a JAR file located locally, specify the file path in the gradle script as follows.

  implementation files("{jar file path}")

Token Issuance

Initialization

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

// config
OndemandClientConfig config = OndemandClientConfig.builder()
        .apiKey("eyJhbGciOiJIUzUxMiJ9.........")
        .build();

// create client
OndemandClient client = 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.

RequestInfo requestInfo = client.doAnalysis(analysisRequest : AnalysisRequest);

Parameters

• analysisRequest Required object
  Three interfaces are provided according to analysis type: SastAnalysisRequest, ScaAnalysisRequest, and DastAnalysisRequest.

  • SastAnalysisRequest
    Downloads analysis files and performs SAST analysis

    SastAnalysisRequest request = SastAnalysisRequest.builder()
                .callbackUrl(...)
                .option(...)
                .build();

    • callbackUrl List
      Sets callbacks when events such as analysis completion and analysis status occur. For convenience, the of method and callback format classes SrcUploadCallback, CompleteCallback, ProgressCallback, and DastProgressCallback are provided.

      • url Required String
        Sets the callback URL
      • type Required List
        Sets the callback type
      • headers List
        • key Required String
          Callback header key
        • value Required String
          Callback header value

    • option Required object
      Can set SAST analysis source code information, analysis options, etc.

      • 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.

      • Other Options

  • ScaAnalysisRequest
    Downloads analysis files and performs SCA analysis

    ScaAnalysisRequest request = ScaAnalysisRequest.builder()
                .callbackUrl(...)
                .option(...)
                .build();

    • callbackUrl List
      Sets callbacks when events such as analysis completion and analysis status occur. For convenience, the of method and callback format classes SrcUploadCallback, CompleteCallback, ProgressCallback, and DastProgressCallback are provided.

      • url Required String
        Sets the callback URL
      • type Required List
        Sets the callback type
      • headers List
        • key Required String
          Callback header key
        • value Required String
          Callback header value

    • option Required object
      Can set SCA analysis source code information, analysis options, etc.

      • 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.

      • Other Options

  • DastAnalysisRequest
    Performs DAST analysis by entering the target URL for vulnerability analysis.

    DastAnalysisRequest request = DastAnalysisRequest.builder()
               .option(...)
               .build();

    • callbackUrl List
      Sets callbacks when events such as analysis completion and analysis status occur. For convenience, the of method and callback format classes SrcUploadCallback, CompleteCallback, ProgressCallback, and DastProgressCallback are provided.
      • url Required String
        Sets the callback URL
      • type Required List
        Sets the callback type
      • headers List
        • key Required String
          Callback header key
        • value Required String
          Callback header value
    • option Required object
      • Options

Return Value

• RequestInfo object

Example Code

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

// Sast
SastAnalysisRequest request1 = SastAnalysisReqeust.builder()
                .callbackUrl(
                        Arrays.asList(
                                CallbackUrl.of("url",
                                        Arrays.asList(CallbackType.ANALYSIS_PROGRESS),
                                        Arrays.asList(CallbackHeader.of("key", "value"))
                                )))
                .option(
                        SastOptionRequest.builder()
                                .analysisSource(
                                        AnalysisSourceRequest.VCS.builder()
                                                .url("https://github.com/jhkim593/PayProject.git")
                                                .branch("master")
                                                .authToken("authToken")        // Set only one of password or authToken
                                                .build())
                                .extensions(Arrays.asList("java"))
                                .issueSimilarity(true)
                                .build())
                .build();
RequestInfo requestInfo1 = client.doAnalysis(request1);
//Sca
ScaAnalysisReqeust request2 = ScaAnalysisReqeust.builder()
        .callbackUrl(
                Arrays.asList(
                        CallbackUrl.of("url",
                                Arrays.asList(CallbackType.ANALYSIS_PROGRESS),
                                Arrays.asList(CallbackHeader.of("key", "value"))
                        )))
        .option(
                ScaOptionRequest.builder()
                        .analysisSource(
                                AnalysisSourceRequest.ObjectStorage.builder()
                                        .endPoint("endpoint")
                                        .bucket("bucket")
                                        .object("object")
                                        .accessKey("accessKey")
                                        .secretKey("secretKey")
                                        .build())
                        .extensions(Arrays.asList("*"))
                        .sbomCreatorEmail("DD")
                        .build())
        .build();
RequestInfo requestInfo2 = client.doAnalysis(request2);
//Dast
DastAnalysisRequest request3 = DastAnalysisRequest.builder()
        .option(

                DastOptionRequest.builder()
                        .crawlerTargetSeedUrls(Arrays.asList("http://52.78.58.6:38380/dcta-for-java/absolutePathDisclosure"))
                        .build())
        .build();
RequestInfo requestInfo3 = client.doAnalysis(request3);

Call the doAnalysis method with each tool's AnalysisRequest as a parameter.
Returns RequestInfo as a response.

2. Request Status Check

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

RequestInfo requestInfo = client.getRequest(requestId: Long)

Parameters

• requestId Required Long
  Request ID.

Return Value

• RequestInfo object

3. Analysis Status Check

If the analysis request was successful, you can check the status of the ongoing analysis. Type casting is possible with detailed information for each tool: SastAnalysisInfo, ScaAnalysisInfo, and DastAnalysisInfo.

AnalysisInfo analysisInfo = client.getAnalysis(analysisId: Long)

Parameters

• analysisId Required Long
  Analysis ID.

Return Value

• AnalysisInfo object

4. Analysis Result File Download

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

client.downLoadAnalysisResult(analysisId: Long  ,filePath: String);

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

Parameters

• analysisId Required Long
  Analysis ID.
• 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

None

5. Analysis Result Reader Creation

If analysis is completed, you can receive an analysis result Reader object.

ResultReader resultReader = client.getAnalysiResultReader(analysisId: Long ,filePath: String);

When you call the getAnalysiResultReader method, the analysis result is downloaded to the path, then extracted to a directory with the analysisId in the same path. A Reader object is created for the extracted files.

Parameters

• analysisId Required Long
  Analysis ID.
• 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

• ResultReader object SastResultReader, ScaResultReader, and DastResultReader are provided, and type casting is required for each tool.

  SastResultReader sastResultReader = (SastResultReader) client.getAnalysiResultReader(analysisId: Long ,filePath: String);
  ScaResultReader scaResultReader = (ScaResultReader) client.getAnalysiResultReader(analysisId: Long ,filePath: String);
  DastResultReader dastResultReader = (DastResultReader) client.getAnalysiResultReader(analysisId: Long ,filePath: String);

  • SastResultReader object

    readSummary method

    Returns analysis result summary information.

    SastSummary sastSummary = sastResultReader.readSummary();

    • Parameters None

    • Return Value

    • SastSummary

    readAsset method

    Returns analysis asset list.

    List<String> assets = sastResultReader.readAsset();

    • Parameters None

    • Return Value List< String >

    issueSize method

    Returns the total number of issue files.

      int size = sastResultReader.issueSize();

    • Parameters None

    • Return Value

    • size int Total number of issue files

    readIssue method

    Reads the issue file and returns a SastIssue list.

      List<SastIssue> sastIssues = sastResultReader.readIssue(index: int);

    • Parameters
      • index Issue file index starting from 1. The maximum index can be checked through the issueSize() method.
    • Return Value List< SastIssue >

    readWorkMessage method

    Reads messages that occur during analysis and returns a WorkMessage list.

      List<WorkMessage> workMessages = sastResultReader.readWorkMessage();

    • Parameters None

    • Return Value List< WorkMessage >

    • ScaResultReader object

    readSummary method

    Returns analysis result summary information.

      ScaSummary scaSummary = scaResultReader.readSummary();

    • Parameters None

    • Return Value ScaSummary

    readAsset method

    Returns analysis asset list.

      List<String> assets = scaResultReader.readAsset();

    • Parameters None

    • Return Value List< String >

    issueSize method

    Returns the total number of issue files.

      int size = scaResultReader.issueSize();

    • Parameters None

    • Return Value int

    readIssue method

    Reads the issue file and returns a ScaComponent list.

      List<ScaComponent> scaComponents = scaResultReader.readIssue(index: int);

    • Parameters
      • index Issue file index starting from 1. The maximum index can be checked through the issueSize() method.
    • Return Value List< ScaComponent >

    readWorkMessage method

    Reads messages that occur during analysis and returns a WorkMessage list.

      List<WorkMessage> workMessages = scaResultReader.readWorkMessage();

    • Parameters None

    • Return Value List< WorkMessage >

    getSbomPath method

    Receives sbomType and returns the SBOM path corresponding to that type.

      Path sbomPath = scaResultReader.getSbomPath(sbomType: SbomType);

    • Parameters

      • sbomType Required SBOM type

    • Return Value

      • sbomPath Path SBOM file path

    getLicenseNoticeHtmlPath method

    Returns the license notice file (HTML) path.

      Path path = scaResultReader.getLicenseNoticeHtmlPath();

    • Parameters None

    • Return Value

      • path Path License notice file (HTML) path

    getLicenseNoticeMarkDownPath method

    Returns the license notice file (Markdown) path.

      Path path = scaResultReader.getLicenseNoticeMarkDownPath();

    • Parameters None

    • Return Value

      • path Path License notice file (Markdown) path

    getLicenseNoticeTextPath method

    Returns the license notice file (Text) path.

      Path path = scaResultReader.getLicenseNoticeTextPath();

    • Parameters None

    • Return Value

      • path Path License notice file (Text) path

  • DastResultReader object

    readSummary method

    Returns analysis result summary information.

      DastSummary dastSummary = dastResultReader.readSummary();

    • Parameters None

    • Return Value DastSummary

    readAsset method

    Returns analysis asset list.

      List<String> assets = dastResultReader.readAsset();

    • Parameters None

    • Return Value List< String >

    issueSize method

    Returns the total number of issue files.

      int size = dastResultReader.issueSize();

    • Parameters None

    • Return Value int

    readIssue method

    Reads the issue file and returns a DastIssue list.

        List<DastIssue> dastIssues = dastResultReader.readIssue(index: int);

    • Parameters
    • index Issue file index starting from 1. The maximum index can be checked through the issueSize() method.
    • Return Value List< DastIssue >
    readWorkMessage method

    Reads messages that occur during analysis and returns a WorkMessage list.

      List<WorkMessage> workMessages = dastResultReader.readWorkMessage();

    • Parameters None

    • Return Value List< WorkMessage >

6. Stop Analysis

You can stop an ongoing analysis.

client.analysisStop(analysisId: Long);

Parameters

• analysisId Required Long
  Analysis ID.

Return Value

None

---

RequestInfo

• id Long Request ID
• accountId Long User ID
• operationType String
  Request type
• requestVersion String
  Analysis result format version
• stopAnalysisId Long
  Analysis ID for which stop was requested
• status String
  Request status
• result String
  Request result
• insertTime Timestamp Time when the request was registered
• updateTime Timestamp Time when the request was last modified
• analysisList List< AnalysisInfo >
  Analysis list

AnalysisInfo

• id Long
  Analysis ID
• requestId Long
  Analysis request ID
• status String
  Analysis status
• result String
  Analysis result
• progress Integer
  Analysis progress rate
• toolType String
  Analysis type
• memo String
  Analysis memo
• startTime TimeStamp
  Analysis start time
• endTime TimeStamp
  Analysis end time
• issueCount Long
  Total number of issues detected in the analysis
• issueCountRisk1 Long
  Number of issues with 'Low' risk level
• issueCountRisk2 Long
  Number of issues with 'Medium' risk level
• issueCountRisk3 Long
  Number of issues with 'High' risk level
• issueCountRisk4 Long
  Number of issues with 'Critical' risk level
• issueCountRisk5 Long
  Number of issues with 'Very Critical' risk level

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 int
    Indicates the response status code.
  • validationErrors
    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.

Progress

Indicates the analysis result value.

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