버전: 2508.1

Sparrow On-Demand Java SDK

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

환경 설정

JDK 17 이상 설치

Gradle 설정

implementation 'io.github.sparrow-co-ltd:sparrow-ondemand-java-sdk:2.0.0'

Sparrow On-Demand API 토큰 필요

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

초기화

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

// config
OndemandClientConfig config = OndemandClientConfig.builder()
        .apiKey("API_KEY")
        .url("API_URL")
        .build();

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

apiKey API 요청에서 인증에 사용하기 위해 Sparrow On-Demand에서 발급 받은 토큰(API_KEY)입니다.
url API 요청을 전송할 Sparrow On-Demand의 API 서비스 URL(API_URL)입니다.

분석 요청

공통 메소드

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

RequestInfo requestInfo = client.doAnalysis(analysisRequest);

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

소스코드 분석

SastAnalysisRequest request1 = SastAnalysisReqeust.builder()
        .callbacks(Arrays.asList(
            callbacks.of("url",
              Arrays.asList(CallbackType.ANALYSIS_PROGRESS),
              Arrays.asList(CallbackHeader.of("key", "value"))
                    )))
        .sastOptions(SastOptionRequest.builder()
            .analysisSource(
                AnalysisSourceRequest.VCS.builder()
                    .url("https://github.com/jhkim593/PayProject.git")
                    .branch("master")
                    .authToken("authToken")
                    .build())
            .extensions(Arrays.asList("java"))
            .issueSimilarity(true)
            .build())
        build();
RequestInfo requestInfo = client.doAnalysis(request);

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

🔽 소스코드 분석 옵션

sastOptions
- analysisSource
  - VCS
    - url VCS URL 필수 String
    - branch 브랜치 String
    - commitId 커밋 ID String
    - tag 태그 String
    - id VCS ID String
    - password VCS 비밀번호 String
    - authToken VCS 토큰 String
    Tip: url만 입력하는 경우 Git 저장소에 기본값으로 설정된 브랜치의 최신 커밋에 포함된 파일을 분석합니다.
  - ObjectStorage
    - endPoint 스토리지 엔드포인트 필수 String
    - bucket 스토리지 버킷 필수 String
    - object 스토리지 오브젝트 이름 필수 String
    - accessKey 스토리지 액세스 키 String
    - secretKey 스토리지 시크릿 키 String
- extensions 분석 대상 파일 확장자 목록
  Tip: 다음 중 하나와 같이 입력하세요.
  - ["java", "go"]
  - ["*"] 압축 파일의 경우 압축 파일의 확장자가 분석 대상자에 해당하면 압축 파일 안에 있는 모든 파일이 분석에 포함됩니다.
- excludedPath 분석 제외 경로
  Tip: 대소문자를 구분하지 않으며 *를 사용할 수 있습니다.
  - *AA*: AA가 포함된 모든 문자열과 일치
  - AA* : AA로 시작하는 모든 문자열과 일치 다른 방법으로 분석 제외 경로를 설정하려는 경우 아래를 참고하세요.
- maxSourceSize 최대 소스 크기 integer 소스코드 분석 또는 오픈소스 분석에서 검사할 분석 대상의 최대 크기입니다. 소스코드 분석 또는 오픈소스 분석을 수행하는 동안 내려받은 분석 대상의 크기가 SOURCE_SIZE보다 크면 분석이 종료됩니다. 1부터 200 사이의 정수를 입력할 수 있습니다.(단위: MB)

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

오픈소스 분석

ScaAnalysisReqeust request = ScaAnalysisReqeust.builder()
        .callbacks(Arrays.asList(
            Arrays.asList(
                CallbackUrl.of("url",
                    Arrays.asList(CallbackType.ANALYSIS_PROGRESS),
                    Arrays.asList(CallbackHeader.of("key", "value"))
                )))
        .scaOptions(ScaOptionRequest.builder()
            .analysisSource(
                AnalysisSourceRequest.ObjectStorage.builder()
                    .endPoint("endpoint")
                    .bucket("bucket")
                    .object("object")
                    .accessKey("accessKey")
                    .secretKey("secretKey")
                    .build())
            .sbomCreatorEmail("DD")
            .build())
        .build();
RequestInfo requestInfo = client.doAnalysis(request);

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

🔽 오픈소스 분석 옵션

scaOptions
- analysisSource
  - VCS
    - url Git URL 필수 String
    - branch 브랜치 String
    - commitId 커밋 ID String
    - tag 태그 String
    - id VCS ID String
    - password VCS 비밀번호 String
    - authToken VCS 토큰 String
    Tip: url만 입력하는 경우 Git 저장소에 기본값으로 설정된 브랜치의 최신 커밋에 포함된 파일을 분석합니다.
  - ObjectStorage
    - endPoint 스토리지 엔드포인트 필수 String
    - bucket 스토리지 버킷 필수 String
    - object 스토리지 오브젝트 이름 필수 String
    - accessKey 스토리지 액세스 키 String
    - secretKey 스토리지 시크릿 키 String
- extensions 분석 대상 파일 확장자 목록
  Tip: 다음 중 하나와 같이 입력하세요.
  - ["java", "go"]
  - ["*"] 압축 파일의 경우 압축 파일의 확장자가 분석 대상자에 해당하면 압축 파일 안에 있는 모든 파일이 분석에 포함됩니다.
- excludedPath 분석 제외 경로
  Tip: 대소문자를 구분하지 않으며 *를 사용할 수 있습니다.
  - *AA*: AA가 포함된 모든 문자열과 일치
  - AA* : AA로 시작하는 모든 문자열과 일치 다른 방법으로 분석 제외 경로를 설정하려는 경우 아래를 참고하세요.
- maxSourceSize 최대 소스 크기 integer 소스코드 분석 또는 오픈소스 분석에서 검사할 분석 대상의 최대 크기입니다. 소스코드 분석 또는 오픈소스 분석을 수행하는 동안 내려받은 분석 대상의 크기가 SOURCE_SIZE보다 크면 분석이 종료됩니다. 1부터 200 사이의 정수를 입력할 수 있습니다.(단위: MB)
- sbomTypes SBOM 유형 목록 빈 목록의 경우 SBOM을 생성하지 않습니다. 다음과 같은 값을 입력할 수 있습니다.
  - SPDX 2.2: SPDX22 (.spdx), SPDX22_JSON (.json), SPDX22_SPREADSHEET (.xlsx), SPDX22_RDF (.rdf)
  - SPDX 2.3: SPDX23 (.spdx), SPDX23_JSON (.json), SPDX23_SPREADSHEET (.xlsx), SPDX23_RDF (.rdf)
  - SPDX 3.0: SPDX30_JSON (.json)
  - CycloneDX: CycloneDX14, CycloneDX15, CycloneDX16 (.json)
  - SWID: SWID (.zip)
  - NIS SBOM: NIS_CSV (.csv), NIS_PDF (.pdf), NIS_JSON (.json)
- sbomCreatorUsername SBOM 생성자 string
- sbomCreatorEmail SBOM 생성자 이메일 string

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

웹취약점 분석

DastAnalysisRequest request = DastAnalysisRequest.builder()
        .callbacks(Arrays.asList(
            DastProgressCallback.of("https://example.com/callback")
        ))
        .dastOptions(
                DastOptionRequest.builder()
                        .crawlerTargetSeedUrls(Arrays.asList("http://52.78.58.6:38380/dcta-for-java/absolutePathDisclosure"))
                        .build())
        .build();
RequestInfo requestInfo = client.doAnalysis(request);

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

🔽 웹취약점 분석 옵션

crawlerTargetSeedUrls 분석 대상 URL 필수 String
commonRecordsLogin 로그인 기록 파일 string

Tip: Sparrow Event Clipboard를 다운로드하고 로그인 과정을 파일로 저장해서 사용하세요.
crawlerTargetContainEntireSeed 하위 경로만 수집 boolean
crawlerRequestAcceptLanguage 클라이언트 언어

Tip: ko_KR과 같은 로케일 형식으로 입력하세요.
crawlerCrawlMaxUrl 최대 수집 URL 수 integer

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

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

Tip: 분석할 수 있는 시간을 제한하지 않으려면 기본값인 0을 입력하세요.
crawlerSkipUrl 제외할 수집 URL string
analyzerSkipUrl 제외할 분석 URL string
crawlerSkipUrlSuffix 제외할 URL 접미사 string
crawlerExcludeCssSelector 이벤트 수행 제외 요소 (CSS 선택자)
crawlerIncludeCssSelector 이벤트 수행 추가 요소 (CSS 선택자)
crawlerExcludeXpath 이벤트 수행 제외 요소 (XPath)
crawlerIncludeXpath 이벤트 수행 추가 요소 (XPath)
crawlerRequestCustomHeaders 사용자 정의 HTTP 헤더
crawlerLimitUrlDepthDegree URL 수집 깊이

Tip: high, medium, low으로 입력하세요.
crawlerLimitDomDepthDegree DOM 수집 깊이

Tip: high, medium, low으로 입력하세요.
crawlerBrowserExplicitTimeout 이벤트 대기 시간 integer
crawlerRequestCountPerSecond HTTP 요청 횟수 integer

Tip: 전송할 수 있는 HTTP 요청의 개수를 제한하지 않으려면 기본값인 -1을 입력하세요.
crawlerClientTimeout HTTP 클라이언트 대기 시간 integer

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

상태 조회

요청 상태 조회

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

RequestInfo requestInfo = client.getRequest(requestId: Long)

requestId 요청 ID 필수 Long

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

분석 상태 조회

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

AnalysisInfo analysisInfo = client.getAnalysis(analysisId: Long)

analysisId 분석 ID 필수 Long

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

분석 결과 파일 다운로드

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

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

downLoadAnalysisResult
- analysisId 분석 ID 필수 Long
- filePath 다운로드 경로 필수 String
  
  Tip : 다운로드 경로에는 zip 확장자가 포함된 파일 이름을 입력하세요. /home/result.zip

분석 결과 읽어오기

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

공통 메소드

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

ResultReader 분석 유형별 결과 읽어오기 객체
- SastResultReader 소스코드 분석 결과 읽어오기
- ScaResultReader 오픈소스 분석 결과 읽어오기
- DastResultReader 웹취약점 분석 결과 읽어오기

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

// 1. SastResultReader 생성
SastResultReader sastResultReader = (SastResultReader) client.getAnalysiResultReader(analysisId: Long ,filePath: String);

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

// 3. 분석 자산 목록 읽어오기
List<String> assets = sastResultReader.readAsset();

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

// 5. 이슈 파일에서 SastIssue 목록 반환하기
List<SastIssue> sastIssues = sastResultReader.readIssue(index: int);

// 6. 작업 메시지에서 WorkMessage 목록 반환하기
List<WorkMessage> workMessages = sastResultReader.readWorkMessage();

SastResultReader
- analysisId 분석 ID 필수 Long
- filePath 다운로드 경로 필수 String
readSummary 분석 결과 요약 읽어오기 메소드
readAsset 분석 자산 목록 읽어오기 메소드

Tip: List<String>을 반환합니다.
issueSize 이슈 파일의 개수 반환하기 메소드

Tip: size int 를 반환합니다.
readIssue SastIssue 목록 반환하기 메소드
- index
  
  Tip: List<SastIssue>를 반환하며 최대값은 issueSize() 메소드를 통해 확인할 수 있습니다.
readWorkMessage WorkMessage 목록 반환하기 메소드

Tip: List<WorkMessage>를 반환합니다.

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

// 1. ScaResultReader 생성
ScaResultReader scaResultReader = (ScaResultReader) client.getAnalysiResultReader(analysisId: Long ,filePath: String);

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

// 3. 분석 자산 목록 읽어오기
List<String> assets = scaResultReader.readAsset();

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

// 5. 이슈 파일에서 SastIssue 목록 반환하기
List<ScaComponent> scaComponents = scaResultReader.readIssue(index: int);

// 6. 작업 메시지에서 WorkMessage 목록 반환하기
List<WorkMessage> workMessages = scaResultReader.readWorkMessage();

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

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

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

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

SastResultReader
- analysisId 분석 ID 필수 Long
- filePath 다운로드 경로 필수 String
readSummary 분석 결과 요약 읽어오기 메소드
readAsset 분석 자산 목록 읽어오기 메소드

Tip: List<String>을 반환합니다.
issueSize 이슈 파일의 개수 반환하기 메소드

Tip: size int를 반환합니다.
readIssue SastIssue 목록 반환하기 메소드
- index
  
  Tip: List<SastIssue>를 반환하며 최대값은 issueSize() 메소드를 통해 확인할 수 있습니다.
readWorkMessage WorkMessage 목록 반환하기 메소드

Tip: List<WorkMessage>를 반환합니다.
getSbomPath SBOM 파일 경로 반환하기 메소드
- sbomType SBOM 타입 필수
Tip: SBOM 파일 경로 sbomPath를 반환합니다.
getLicenseNoticeHtmlPath 라이선스 고지문 파일(HTML) 경로 반환하기 메소드

Tip: 라이선스 고지문 파일 경로 path를 반환합니다.
getLicenseNoticeMarkDownPath 라이선스 고지문 파일(Markdown) 경로 반환하기 메소드

Tip: 라이선스 고지문 파일 경로 path를 반환합니다.
getLicenseNoticeTextPath 라이선스 고지문 파일(Text) 경로 반환하기 메소드

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

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

// 1. DastResultReader 생성
DastResultReader dastResultReader = (DastResultReader) client.getAnalysiResultReader(analysisId: Long ,filePath: String);

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

// 3. 분석 자산 목록 읽어오기
List<String> assets = dastResultReader.readAsset();

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

// 5. 이슈 파일에서 SastIssue 목록 반환하기
List<DastIssue> dastIssues = dastResultReader.readIssue(index: int);

// 6. 작업 메시지에서 WorkMessage 목록 반환하기
List<WorkMessage> workMessages = dastResultReader.readWorkMessage();

SastResultReader
- analysisId 분석 ID 필수 Long
- filePath 다운로드 경로 필수 String
readSummary 분석 결과 요약 읽어오기 메소드
readAsset 분석 자산 목록 읽어오기 메소드

Tip: List<String>을 반환합니다.
issueSize 이슈 파일의 개수 반환하기 메소드

Tip: size int를 반환합니다.
readIssue SastIssue 목록 반환하기 메소드
- index
  
  Tip: List<SastIssue>를 반환하며 최대값은 issueSize() 메소드를 통해 확인할 수 있습니다.
readWorkMessage WorkMessage 목록 반환하기 메소드

Tip: List<WorkMessage>를 반환합니다.

분석 중지

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

client.stopAnalysis(analysisId: Long);

analysisId 분석 ID 필수 Long

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

예외 처리

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

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

객체 정보

RequestInfo

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

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

AnalysisInfo

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

목차​

환경 설정​

초기화​

분석 요청​

공통 메소드​

소스코드 분석​

오픈소스 분석​

웹취약점 분석​

상태 조회​

요청 상태 조회​

분석 상태 조회​

분석 결과 파일 다운로드​

분석 결과 읽어오기​

공통 메소드​

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

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

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

분석 중지​

예외 처리​

객체 정보​

RequestInfo​

AnalysisInfo​

목차

환경 설정

초기화

분석 요청

공통 메소드

소스코드 분석

오픈소스 분석

웹취약점 분석

상태 조회

요청 상태 조회

분석 상태 조회

분석 결과 파일 다운로드

분석 결과 읽어오기

공통 메소드

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

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

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

분석 중지

예외 처리

객체 정보

RequestInfo

AnalysisInfo