Version: 2504.1

요구사항

JDK 17 이상

개발 환경 설정

Maven Repository 사용
Maven Repository 사용해 sdk를 사용할 수 있습니다. gradle 스크립트에 아래와 같이 추가합니다.
```
implementation 'com.sparrow.ondemand:sparrow-ondemand-java-sdk:1.0.0'
```
로컬 JAR 사용
로컬에 위치한 JAR 파일을 사용하려면 gradle 스크립트에 아래와 같이 파일 경로를 명시합니다.
```
implementation files("{jar 파일 경로}")
```

토큰 발급

초기화

ondemand 분석 관련 요청을 위해 아래의 코드를 추가해 OndemandClient 인스턴스를 생성합니다.

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

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

OndemandClientConfig 는 OndemandClient 생성시 설정 값 지정을 위해 사용됩니다.

apiKey : api 요청시 인증을 위해 3에서 발급 받은 토큰 입력

분석 메소드

생성한 client의 메소드를 통해 분석을 수행합니다. 메소드 동작시 OndemandException이 발생 할 수 있습니다. 예외에 대한 자세한 내용은 아래를 참고해주세요

1. 분석 요청

생성한 client로 분석 요청을 전송할 수 있습니다.

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

파라미터

analysisRequest 필수 object
분석 타입 별로 SastAnalysisRequest , ScaAnalysisRequest , DastAnalysisRequest 3가지 인터페이스를 제공합니다.
- SastAnalysisRequest
  분석 파일을 다운로드 받아서 Sast 분석을 수행합니다
```
SastAnalysisRequest request = SastAnalysisRequest.builder()
            .callbackUrl(...)
            .option(...)
            .build();
```
  - callbackUrl List
    분석 종료 , 분석 상태 등 이벤트가 발생했을 때 콜백을 설정합니다. 생성 편의를 위해 of 메소드와 전송되는 콜백 형식인 SrcUploadCallback , CompleteCallback, ProgressCallback, DastProgressCallback 클래스를 제공합니다.
    - url 필수 String
      콜백 url 설정
    - type 필수 List
      콜백 타입을 설정
    - headers List
      - key 필수 String
        콜백 header 키
      - value 필수 String
        콜백 header 값
  - option 필수 object
    Sast 분석 소스코드 정보, 분석 옵션 등을 설정할 수 있습니다.
    - analysisSource 필수 object
      분석할 파일이 저장된 저장소이며 VCS , ObjectStorage 타입을 지원합니다.
      - VCS
        
        url 필수 String
        분석할 파일이 저장된 저장소의 url입니다.
        
        branch String
        저장소 중 분석하려는 파일이 업로드된 브랜치의 이름입니다. 입력하지 않았을 때 default 브랜치를 타겟으로 분석합니다.
        
        tag String
        분석하려는 브랜치의 태그 정보입니다.
        
        commitId String
        분석 하려는 커밋 아이디 정보입니다.
        
        id String
        VCS 인증을 위한 id입니다.
        
        password String
        VCS 인증을 위한 password 입니다. id와 같이 입력되야하며 authToken과 동시에 입력될 수 없습니다.
        
        authToken String
        VCS 인증을 위한 authToken 이며 id, password와 동시에 입력될 수 없습니다.
      - ObjectStorage
        
        bucket 필수 String
        분석할 파일의 bucket입니다.
        
        object 필수 String
        분석할 파일의 object 경로입니다.
        
        endPoint 필수 String
        분석할 버켓이 위치한 endPoint입니다.
        
        accessKey String
        인증을 위한 accessKey입니다.
        
        secretKey String
        인증을 위한 secretKey입니다.
    - 그 외 옵션
- ScaAnalysisRequest
  분석 파일을 다운로드 받아서 Sca 분석을 수행합니다
```
ScaAnalysisRequest request = ScaAnalysisRequest.builder()
            .callbackUrl(...)
            .option(...)
            .build();
```
  - callbackUrl List
    분석 종료 , 분석 상태 등 이벤트가 발생했을 때 콜백을 설정합니다. 생성 편의를 위해 of 메소드와 전송되는 콜백 형식인 SrcUploadCallback , CompleteCallback, ProgressCallback, DastProgressCallback 클래스를 제공합니다.
    - url 필수 String
      콜백 url 설정
    - type 필수 List
      콜백 타입을 설정
    - headers List
      - key 필수 String
        콜백 header 키
      - value 필수 String
        콜백 header 값
  - option 필수 object
    Sca 분석 소스코드 정보, 분석 옵션 등을 설정할 수 있습니다.
    - analysisSource 필수 object
      분석할 파일이 저장된 저장소이며 VCS , ObjectStorage 타입을 지원합니다.
      - VCS
        
        url 필수 String
        분석할 파일이 저장된 저장소의 url입니다.
        
        branch String
        저장소 중 분석하려는 파일이 업로드된 브랜치의 이름입니다. 입력하지 않았을 때 default 브랜치를 타겟으로 분석합니다.
        
        tag String
        분석하려는 브랜치의 태그 정보입니다.
        
        commitId String
        분석 하려는 커밋 아이디 정보입니다.
        
        id String
        VCS 인증을 위한 id입니다.
        
        password String
        VCS 인증을 위한 password 입니다. id와 같이 입력되야하며 authToken과 동시에 입력될 수 없습니다.
        
        authToken String
        VCS 인증을 위한 authToken 이며 id, password와 동시에 입력될 수 없습니다.
      - ObjectStorage
        
        bucket 필수 String
        분석할 파일의 bucket입니다.
        
        object 필수 String
        분석할 파일의 object 경로입니다.
        
        endPoint 필수 String
        분석할 버켓이 위치한 endPoint입니다.
        
        accessKey String
        인증을 위한 accessKey입니다.
        
        secretKey String
        인증을 위한 secretKey입니다.
    - 그 외 옵션
- DastAnalysisRequest
  취약점 분석 대상 url을 입력해 Dast 분석을 수행합니다.
```
DastAnalysisRequest request = DastAnalysisRequest.builder()
           .option(...)
           .build();
```
  - callbackUrl List
    분석 종료 , 분석 상태 등 이벤트가 발생했을 때 콜백을 설정합니다. 생성 편의를 위해 of 메소드와 전송되는 콜백 형식인 SrcUploadCallback , CompleteCallback, ProgressCallback, DastProgressCallback 클래스를 제공합니다.
    - url 필수 String
      콜백 url 설정
    - type 필수 List
      콜백 타입을 설정
    - headers List
      - key 필수 String
        콜백 header 키
      - value 필수 String
        콜백 header 값
  - option 필수 object
    - 옵션

반환값

RequestInfo object

예시 코드

Sast VCS 분석 , Sca ObjectStorage 분석, Dast 분석을 요청하는 예시 코드입니다.

// 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")        //password, 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);

각 도구별 AnalysisRequest를 파라미터로 doAnalysis 메소드를 호출합니다.
응답으로 RequestInfo를 반환합니다.

2. 요청 상태 확인

분석 요청이 정상적으로 됐다면 요청 상태를 확인 할 수 있습니다.

RequestInfo requestInfo = client.getRequest(requestId: Long)

파라미터

requestId 필수 Long
요청 id입니다.

반환값

RequestInfo object

3. 분석 상태 확인

분석 요청이 정상적으로 됐다면 진행 중인 분석 상태를 확인 할 수 있습니다. 각 도구별 상세 정보인 SastAnalysisInfo , ScaAnalysisInfo , DastAnalysisInfo로 타입 캐스팅이 가능합니다.

AnalysisInfo analysisInfo = client.getAnalysis(analysisId: Long)

파라미터

analysisId 필수 Long
분석 id입니다.

반환값

AnalysisInfo object

4. 분석 결과 파일 다운로드

분석이 완료됐다면 분석 결과 파일을 다운로드 받을 수 있습니다.

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

downLoadAnalysisResult 메소드를 호출하면 지정한 file path에 분석 결과 파일이 다운로드됩니다.

파라미터

analysisId 필수 Long
분석 id입니다.
filePath 필수 String
분석 다운로드 file path 입니다. path에는 파일 이름까지 명시돼야하며 zip 확장자만 지원합니다.
ex) /home/result.zip

반환값

없음

5. 분석 결과 Reader 생성

분석이 완료됐다면 분석 결과 Reader 객체를 반환 받을 수 있습니다.

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

getAnalysiResultReader 메소드를 호출하게되면 path 경로에 분석 결과를 다운로드 받은 후 같은 경로 analysisId로 디렉토리로 압축 해제합니다. 압축 해제된 파일을 대상으로 Reader 객체가 생성됩니다.

파라미터

analysisId 필수 Long
분석 id입니다.
filePath 필수 String
분석 다운로드 file path 입니다. path에는 파일 이름까지 명시돼야하며 zip 확장자만 지원합니다.
ex) /home/result.zip

반환값

ResultReader object SastResultReader , ScaResultReader , DastResultReader가 제공되며 도구별로 타입 캐스팅을 필수로 해야합니다.
```
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
  분석 결과 요약 정보를 반환합니다.
  SastSummary sastSummary = sastResultReader.readSummary();
  
  파라미터 없음
  
  반환값
  
  SastSummary
  readAsset method
  분석 자산 목록을 반환합니다.
  List<String> assets = sastResultReader.readAsset();
  
  파라미터 없음
  
  반환값 List< String >
  issueSize method
  결과 이슈 파일 총 개수를 반환합니다.
  int size = sastResultReader.issueSize();
  
  파라미터 없음
  
  반환값
  
  size int 이슈 파일 총 개수
  readIssue method
  결과 이슈 파일을 읽어 SastIssue 리스트를 반환합니다.
  List<SastIssue> sastIssues = sastResultReader.readIssue(index: int);
  
  파라미터
  
  index 이슈 파일 index를 의미하며 1부터 시작합니다. 최대 index는 issueSize()를 통해 확인할 수 있습니다.
  
  반환값 List< SastIssue >
  readWorkMessage method
  분석 중 발생하는 메세지를 읽어 WorkMessage 리스트를 반환합니다.
  List<WorkMessage> workMessages = sastResultReader.readWorkMessage();
  
  파라미터 없음
  
  반환값 List< WorkMessage >
  - ScaResultReader object
  readSummary method
  분석 결과 요약 정보를 반환합니다.
  ScaSummary scaSummary = scaResultReader.readSummary();
  
  파라미터 없음
  
  반환값 ScaSummary
  readAsset method
  분석 자산 목록을 반환합니다.
  List<String> assets = scaResultReader.readAsset();
  
  파라미터 없음
  
  반환값 List< String >
  issueSize method
  결과 이슈 파일 총 개수를 반환합니다.
  int size = scaResultReader.issueSize();
  
  파라미터 없음
  
  반환값 int
  readIssue method
  결과 이슈 파일을 읽어 ScaComponent 리스트를 반환합니다.
  List<ScaComponent> scaComponents = scaResultReader.readIssue(index: int);
  
  파라미터
  
  index 이슈 파일 index를 의미하며 1부터 시작합니다. 최대 index는 issueSize()를 통해 확인할 수 있습니다.
  
  반환값 List< ScaComponent >
  readWorkMessage method
  분석 중 발생하는 메세지를 읽어 WorkMessage 리스트를 반환합니다.
  List<WorkMessage> workMessages = scaResultReader.readWorkMessage();
  
  파라미터 없음
  
  반환값 List< WorkMessage >
  getSbomPath method
  sbomType을 받아 해당 타입에 맞는 sbom 경로를 반환합니다.
  Path sbomPath = scaResultReader.getSbomPath(sbomType: SbomType);
  
  파라미터
  
  sbomType 필수 sbom 타입
  
  반환값
  
  sbomPath Path sbom 파일 경로입니다.
  getLicenseNoticeHtmlPath method
  html 타입 라이선스 고지문 파일 경로를 반환합니다.
  Path path = scaResultReader.getLicenseNoticeHtmlPath();
  
  파라미터 없음
  
  반환값
  
  path Path html 타입 라이선스 고지문 파일 경로 입니다.
  getLicenseNoticeMarkDownPath method
  markdown 타입 라이선스 고지문 파일 경로를 반환합니다.
  Path path = scaResultReader.getLicenseNoticeMarkDownPath();
  
  파라미터 없음
  
  반환값
  
  path Path markdown 타입 라이선스 고지문 파일 경로 입니다.
  getLicenseNoticeTextPath method
  텍스트 타입 라이선스 고지문 파일 경로를 반환합니다.
  Path path = scaResultReader.getLicenseNoticeTextPath();
  
  파라미터 없음
  
  반환값
  
  path Path 텍스트 타입 라이선스 고지문 파일 경로 입니다.
- DastResultReader object
  readSummary method
  분석 결과 요약 정보를 반환합니다.
  DastSummary dastSummary = dastResultReader.readSummary();
  
  파라미터 없음
  
  반환값 DastSummary
  readAsset method
  분석 자산 목록을 반환합니다.
  List<String> assets = dastResultReader.readAsset();
  
  파라미터 없음
  
  반환값 List< String >
  issueSize method
  결과 이슈 파일 총 개수를 반환합니다.
  int size = dastResultReader.issueSize();
  
  파라미터 없음
  
  반환값 int
  readIssue method
  결과 이슈 파일을 읽어 DastIssue 리스트를 반환합니다.
  List<DastIssue> dastIssues = dastResultReader.readIssue(index: int);
  
  파라미터
  
  index 이슈 파일 index를 의미하며 1부터 시작합니다. 최대 index는 issueSize()를 통해 확인할 수 있습니다.
  
  반환값 List< DastIssue >
  readWorkMessage method
  분석 중 발생하는 메세지를 읽어 WorkMessage 리스트를 반환합니다.
  List<WorkMessage> workMessages = dastResultReader.readWorkMessage();
  
  파라미터 없음
  
  반환값 List< WorkMessage >

6. 분석 중지

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

client.analysisStop(analysisId: Long);

파라미터

analysisId 필수 Long
분석 id입니다.

반환값

없음

RequestInfo

id Long 요청 아이디
accountId Long 사용자 아이디
operationType String
요청 타입
requestVersion String
분석 결과 형식 버전
stopAnalysisId Long
중지 요청된 분석 id
status String
요청 상태
result String
요청 결과
insertTime Timestamp 요청이 등록된 일시
updateTime Timestamp 요청이 마지막으로 수정된 일시
analysisList List< AnalysisInfo >
분석 목록

AnalysisInfo

id Long
분석 id
requestId Long
분석 요청 id
status String
분석 상태
result String
분석 결과
progress Integer
분석 진행률
toolType String
분석 타입
memo String
분석 메모
startTime TimeStamp
분석 시작 시간
endTime TimeStamp
분석 종료 시간
issueCount Long
분석에서 검출된 총 이슈의 수
issueCountRisk1 Long
위험도가 '낮음'에 해당하는 이슈 수
issueCountRisk2 Long
위험도가 '보통'에 해당하는 이슈 수
issueCountRisk3 Long
위험도가 '높음'에 해당하는 이슈 수
issueCountRisk4 Long
위험도가 '위험'에 해당하는 이슈 수
issueCountRisk5 Long
위험도가 '매우 위험'에 해당하는 이슈 수

OndemandException

OndemandException은 RuntimeException을 통해 예외를 전달하며 두가지로 분류됩니다.

OndmandClientException
온디맨드 서비스에 요청을 보내거나 응답 처리 로직을 수행할 때 클라이언트단에 발생합니다.
- resultCode String
  exception 발생 원인 코드 정보를 담고 있습니다.
- message String
  예외 메세지를 담고있습니다.
OndmandServerException
온디맨드 서비스가 성공적으로 요청을 받지 못했지만 처리하지 못해 에러 응답을 반환하는 경우 발생합니다.
- resultCode String
  exception 발생 원인 코드 정보를 담고 있습니다.
- message string
  예외 메세지를 담고있습니다.
- statusCode int
  응답 상태 코드를 나타냅니다.
- validationErrors
  요청 유효성 검증 실패시 서버에서 반횐되는 상세 실패 메세지입니다.

ANALYSIS_STATUS

분석 상태를 나타내며 7가지로 구분됩니다.

INIT
분석을 진행하기 위한 초기화 진행 중임을 나타냅니다.
READY
초기화 완료 후 분석 준비 진행 중임을 나타냅니다.
PRE_PROCESS
분석을 위한 전처리 진행 중임을 나타냅니다.
ANALYSIS
분석 진행 중임을 나타냅니다.
POST_PROCESS
분석이 완료된 후 결과 처리 진행 중임을 나타냅니다.
COMPLETE
분석, 결과 처리 모두 완료된 상태를 나타냅니다.
STOP
분석이 중지된 상태를 나타냅니다.

ANALYSIS_RESULT

분석 결과값을 나타냅니다.

SUCCESS
분석이 성공했음을 의미합니다.
FAIL
분석이 실패했음을 의미합니다.
STOPPED 분석이 중지됐음을 의미합니다.

Progress

분석 결과값을 나타냅니다.

SUCCESS
분석이 성공했음을 의미합니다.
FAIL
분석이 실패했음을 의미합니다.
STOPPED 분석이 중지됐음을 의미합니다.

개발 환경 설정

토큰 발급

초기화

분석 메소드

1. 분석 요청​

파라미터​

반환값​

예시 코드​

2. 요청 상태 확인​

파라미터​

반환값​

3. 분석 상태 확인​

파라미터​

반환값​

4. 분석 결과 파일 다운로드​

파라미터​

반환값​

5. 분석 결과 Reader 생성​

파라미터​

반환값​

6. 분석 중지​

파라미터​

반환값​

RequestInfo​

AnalysisInfo​

OndemandException​

ANALYSIS_STATUS​

ANALYSIS_RESULT​

Progress​

1. 분석 요청

파라미터

반환값

예시 코드

2. 요청 상태 확인

파라미터

반환값

3. 분석 상태 확인

파라미터

반환값

4. 분석 결과 파일 다운로드

파라미터

반환값

5. 분석 결과 Reader 생성

파라미터

반환값

6. 분석 중지

파라미터

반환값

RequestInfo

AnalysisInfo

OndemandException

ANALYSIS_STATUS

ANALYSIS_RESULT

Progress