Sparrow On-Demand UI 키트

Sparrow On-Demand UI Kit는 Sparrow On-Demand의 API를 손쉽게 연동할 수 있도록 도와주는 React 기반의 UI 컴포넌트 라이브러리입니다. 개발자는 Sparrow On-Demand UI Kit를 사용하여 분석 요청 목록 및 분석 결과 조회와 같은 기능을 빠르게 구현할 수 있습니다.

⚙️ 설치하기

1. 명령어를 사용하여 UI Kit를 설치하세요.

yarn add @sparrowai/ondemand-uikit

Tip: Sparrow OnDemand UI Kit 1.1.3 버전을 지원합니다.

2. peerDependencies를 설치하세요.

yarn add @hookform/resolvers @tanstack/react-table react-hook-form

Tip: 이미 설치된 경우 다시 설치하지 않아도 됩니다.

🍭 UI 키트 구현하기

Sparrow OnDemand UI Kit는 다음과 같이 분석 요청 및 분석 목록이라는 두 가지 컴포넌트를 지원합니다. 해당 컴포넌트는 페이지 템플릿의 형태로 포함되어 있는 UI를 변경할 수 없습니다.

분석 요청 컴포넌트

분석을 요청할 때 사용할 수 있는 UI 컴포넌트입니다.

1. 다음과 같은 코드를 사용하여 Sparrow On-Demand UI Kit 클라이언트를 생성하세요.

import { useState } from "react";
import {
  OndemandClient,
  OndemandClientConfig,
  SparrowAnalysisRequest,
  SparrowOnDemandProvider,
  SparrowAnalysisResult,
} from "@sparrowai/ondemand-uikit";
import "@sparrowai/ondemand-uikit/style.css";

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

  
  const [client] = useState<OndemandClient>(() => {
    return new OndemandClient(config);
  });

  return (
    <SparrowOnDemandProvider client={client}>
      <SparrowAnalysisRequest />
    </SparrowOnDemandProvider>
  );
}

Tip: 아래의 속성을 적절히 변경하세요.

apiKey

API 요청에서 인증에 사용하기 위해 Sparrow On-Demand에서 발급 받은 토큰(API_KEY)입니다.

2. 애플리케이션을 실행하고 분석 요청 컴포넌트가 올바르게 표시되는지 확인하세요.

3. 아래를 참고하여 분석 요청 컴포넌트에서 필요한 정보를 입력하고 분석을 요청하세요.

분석 유형

분석할 유형을 선택합니다. 소스코드 분석, 오픈소스 분석, 웹취약점 분석 중 하나를 선택할 수 있습니다.

분석 대상

분석할 대상을 선택합니다. 소스코드 분석 및 오픈소스 분석의 경우 VCS 저장소 또는 오브젝트 스토리지 중 하나를 선택할 수 있습니다. 웹취약점 분석의 경우 URL을 입력합니다.

VCS 저장소

VCS 정보 VCS 저장소를 선택한 경우, 저장소 URL, 브랜치, 커밋 ID, 태그를 입력합니다.

Tip: 브랜치, 커밋 ID, 태그를 모두 입력하지 않으면 기본 브랜치의 가장 최근 커밋에 포함된 파일을 분석합니다. 둘 이상의 값을 입력한 경우 브랜치, 커밋 ID, 태그순으로 우선순위를 적용합니다.

인증 정보 VCS 저장소에 접근하기 위한 인증 정보를 입력합니다. 사용자 ID와 비밀번호 또는 사용자 ID와 토큰 중 하나를 선택할 수 있습니다.

오브젝트 스토리지

오브젝트 스토리지 정보 오브젝트 스토리지를 선택한 경우, 스토리지 유형, 엔드포인트, 버킷, 오브젝트 이름을 입력합니다.

인증 정보 오브젝트 스토리지에 접근하기 위한 인증 정보입니다. 액세스 키와 시크릿 키를 입력합니다.

분석 대상 URL 웹취약점 분석을 선택한 경우, 분석할 대상 URL을 입력합니다.

분석 요청이 성공적으로 전송되면 확인 메시지가 표시됩니다.

사용자는 분석 옵션을 통해 분석 동작을 세부적으로 제어할 수 있습니다. 다음은 각 분석 유형별로 지원하는 주요 옵션입니다.

소스코드 분석 옵션

• 최대 소스 크기 소스코드 분석 또는 오픈소스 분석에서 검사할 분석 대상의 최대 크기입니다. 소스코드 분석 또는 오픈소스 분석을 수행하는 동안 내려받은 분석 대상의 크기가 입력한 숫자보다 크면 분석이 종료됩니다. 1부터 200 사이의 정수를 입력할 수 있습니다.(단위: MB)

• 분석 대상 파일 확장자 목록 소스코드 분석은 분석 대상에 포함시킬 파일을 확장자로 구분합니다. 압축 파일의 확장자가 분석 대상에 해당하면 압축 파일 안에 있는 모든 파일이 분석에 포함됩니다. 소스코드 분석의 경우 여기에 해당하지 않는 파일은 분석에서 제외됩니다.

• 분석 제외 경로 분석에서 제외할 파일이 있는 경우 해당 파일의 경로(EXCLUDED_PATH1, EXCLUDED_PATH2, EXCLUDED_PATH3)를 입력합니다. 여기에 입력한 경로에 포함된 파일로부터 이슈가 검출되지 않게 됩니다.

오픈소스 분석 옵션

• 최대 소스 크기

  소스코드 분석 또는 오픈소스 분석에서 검사할 분석 대상의 최대 크기입니다. 소스코드 분석 또는 오픈소스 분석을 수행하는 동안 내려받은 분석 대상의 크기가 입력한 숫자보다 크면 분석이 종료됩니다. 1부터 200 사이의 정수를 입력할 수 있습니다.(단위: MB)

• SBOM 유형 목록 수신할 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)

• SBOM 생성자

• SBOM 생성자 이메일

웹취약점 분석 옵션

• 분석 대상 URL 분석할 URL이며 하나만 입력할 수 있습니다. 분석 대상 URL을 입력할 때는 해당 URL에 외부 인터넷이 접근할 수 있는지, 해당 서버에 방화벽이 동작하고 있지 않은지 확인해야 합니다.

• 로그인 기록 파일 목록 로그인 기록 파일은 이벤트 클립보드에서 저장한 .ecl 형식의 파일로써 특정 URL에서 사용자의 동작이 기록되어 있습니다. 주로 사용자가 특정 URL에서 로그인하는 데 사용한 ID 및 비밀번호 정보를 저장하여 URL을 수집하거나 분석할 때 사용합니다.

  로그인 기록 파일을 첨부하는 경우 URL 수집 및 분석 중에 이벤트 클립보드의 기록이 시작된 URL에 도달하면 해당 파일에 저장된 사용자의 동작을 그대로 재현하게 됩니다. 이러한 방법으로 로그인 페이지에서 필요한 인증을 통과할 수 있습니다.

  • Sparrow Event Clipboard를 다운로드하고 로그인 과정을 파일로 저장해서 사용하세요.

• 하위 경로만 수집 하위 경로만 수집은 프로젝트에 입력한 분석 대상 URL을 모두 포함하는 경로만 수집하는지를 의미합니다. 이 옵션을 예로 설정하면 분석 대상 URL을 포함한 하위 경로만 분석하게 됩니다. 이 옵션을 아니요로 설정하면 프로젝트의 분석 대상 URL에 포함된 상위 경로도 분석하게 됩니다.

• 클라이언트 언어 분석 대상인 웹 애플리케이션이 표시되는 브라우저에서 어떤 언어를 설정했고, HTTP 클라이언트가 어떤 언어를 이해할 수 있는지 설정합니다. 언어로 표시되는 로케일 형식으로 입력할 수 있습니다.(기본값: ko)

• 최대 수집 URL 수 최대 수집 URL 수는 분석에서 수집할 수 있는 URL 수의 최대 개수입니다. 너무 많은 URL이 수집될 경우 분석 결과가 정확하지 않을 수 있습니다. 따라서 이 옵션에서 수집할 URL의 최대 개수를 지정하는 것이 좋습니다.(기본값: 0)

  이 옵션에 입력된 값이 클수록 수집할 수 있는 URL의 개수가 늘어나지만 수집을 위한 분석 시간도 증가할 수 있습니다. 이 옵션에 입력된 값이 적을수록 수집할 수 있는 URL 개수가 줄어들어 분석 시간도 줄어듭니다. 아무것도 입력하지 않는 경우 옵션의 기본값은 0이며 이 경우에 수집할 수 있는 URL의 개수를 제한하지 않게 됩니다.

• 최대 수집 시간 최대 수집 시간은 분석에서 URL을 수집할 수 있는 최대 시간입니다. 너무 많은 시간이 걸리는 경우 분석 결과가 정확하지 않을 수 있습니다. 따라서 이 옵션에서 수집 시간을 지정하는 것이 좋습니다.(단위: 분, 기본값: 0)

  이 옵션에 입력된 값이 클수록 수집을 위한 분석 시간이 증가하고 수집할 수 있는 URL의 개수도 늘어날 수 있습니다. 이 옵션에 입력된 값이 적을수록 분석 시간이 감소하고 수집할 수 있는 URL의 개수가 줄어들 수 있습니다. 아무것도 입력하지 않는 경우 옵션의 기본값은 0이며 이 경우에 수집할 수 있는 시간을 제한하지 않게 됩니다.

• 최대 분석 시간 최대 분석 시간은 분석에서 URL을 분석할 수 있는 최대 시간입니다. 너무 많은 시간이 걸리는 경우 분석 결과가 정확하지 않을 수 있습니다. 따라서 이 옵션에서 분석 시간을 지정하는 것이 좋습니다.(단위: 분, 기본값: 0)

  이 옵션에 입력된 값이 클수록 분석 시간이 증가하고 분석의 결과도 늘어날 수 있습니다. 이 옵션에 입력된 값이 적을수록 분석 시간이 감소하고 분석의 결과도 줄어들 수 있습니다. 아무것도 입력하지 않는 경우 옵션의 기본값은 0이며 이 경우에 분석할 수 있는 시간을 제한하지 않게 됩니다.

• 제외할 수집 URL 제외할 수집 URL은 URL에 특정 단어가 포함된 경우 해당 URL을 수집하지 않고 건너뛰는 문자열 목록을 가리킵니다. 하나 이상의 문자열을 입력하고 엔터 또는 쉼표(,)로 구분할 수 있습니다.

  이 옵션에 입력한 목록에 해당하는 단어가 하나라도 수집하려는 URL에 포함되었다면 해당 URL을 수집하지 않게 됩니다. 단, URL을 수집하기 직전에 건너뛰기 때문에 브라우저가 해당 URL에 방문할 수 있습니다.

• 제외할 분석 URL

  제외할 분석 URL은 URL에 특정 단어가 포함된 경우 해당 URL을 분석하지 않고 건너뛰는 문자열 목록을 가리킵니다. 하나 이상의 URL을 입력하고 엔터 또는 쉼표(,)로 구분할 수 있습니다.

  이 옵션에 입력한 목록에 해당하는 단어가 하나라도 분석하려는 URL에 포함되었다면 해당 URL을 분석하지 않게 됩니다.

  Tip: URL로 표시되는 페이지 전체가 아니라 페이지의 동작을 분석에서 제외하려는 경우 아래에 있는 이벤트 수행 제외 요소 옵션을 사용하세요.

• 제외할 URL 접미사

  제외할 URL 접미사는 URL의 끝에 특정 단어나 확장자가 포함된 경우 해당 URL을 수집하지 않고 건너뛰는 접미사 목록을 가리킵니다. 마침표(.)로 시작하는 확장자 형식으로 입력하고 엔터 또는 쉼표(,)로 구분할 수 있습니다.(기본값: .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)

  이 옵션에 입력한 목록에 해당하는 단어가 하나라도 수집하려는 URL의 끝에 포함되었다면 해당 URL을 수집하지 않게 됩니다. URL로 이동하기 전에 HTML 요소의 속성 값 등을 보고 건너뛰기 때문에 해당 URL에 방문하지 않으므로 파일 다운로드 등을 수행하기 전에 건너뛸 수 있습니다.

• 이벤트 수행 제외 요소 (CSS 선택자)

  이벤트 수행 제외 요소 (CSS 선택자)는 URL 수집 과정에서 브라우저가 이벤트를 수행할 때, 이벤트를 수행하지 않고 제외할 HTML 요소를 나타낸 CSS 선택자 목록입니다. 하나 이상의 값을 문자열로 입력하고 엔터 또는 쉼표(,)로 구분할 수 있습니다.

  이 옵션에 입력한 목록에 해당하는 CSS 선택자가 하나라도 페이지에 포함되었다면 해당하는 HTML 요소와 하위 HTML 요소의 이벤트를 모두 수행하지 않게 됩니다. 이러한 방법으로 페이지에서 로그아웃 버튼을 클릭하지 않도록 설정할 수 있습니다.

  • 이벤트 수행 추가 요소 (CSS 선택자)

  이벤트 수행 추가 요소 (CSS 선택자)는 URL 수집 과정에서 이벤트 수행이 가능한 HTML 요소에 포함되지 않아도 이벤트를 무조건 수행할 HTML 요소를 나타낸 CSS 선택자 목록입니다. 하나 이상의 값을 문자열로 입력하고 엔터 또는 쉼표(,)로 구분할 수 있습니다.

  이 옵션에 입력한 목록에 해당하는 CSS 선택자가 하나라도 페이지에 포함되었다면 해당하는 HTML 요소와 하위 HTML 요소의 이벤트를 모두 수행하게 됩니다. 이러한 방법으로 페이지에서 이벤트에 포함되지 않는 태그와 같은 요소를 수행할 수 있습니다.

• 이벤트 수행 제외 요소 (XPath)

  이벤트 수행 제외 요소 (XPath)는 URL 수집 과정에서 브라우저가 이벤트를 수행할 때, 이벤트를 수행하지 않고 제외할 HTML 요소를 나타낸 XPath 목록입니다. 하나 이상의 값을 문자열로 입력하고 엔터 또는 쉼표(,)로 구분할 수 있습니다.

  이 옵션에 입력한 목록에 해당하는 XPath가 하나라도 페이지에 포함되었다면 해당하는 HTML 요소와 하위 HTML 요소의 이벤트를 모두 수행하지 않게 됩니다. 이러한 방법으로 페이지에서 로그아웃 버튼을 클릭하지 않도록 설정할 수 있습니다.

• 이벤트 수행 추가 요소 (XPath)

  이벤트 수행 추가 요소 (XPath)는 URL 수집 과정에서 이벤트 수행이 가능한 HTML 요소에 포함되지 않아도 이벤트를 무조건 수행할 HTML 요소를 나타낸 XPath 목록입니다. 하나 이상의 값을 문자열로 입력하고 엔터 또는 쉼표(,)로 구분할 수 있습니다.

  이 옵션에 입력한 목록에 해당하는 XPath가 하나라도 페이지에 포함되었다면 해당하는 HTML 요소와 그 하위 HTML 요소의 이벤트를 모두 수행하게 됩니다. 이러한 방법으로 페이지에서 이벤트에 포함되지 않는 태그와 같은 요소를 수행할 수 있습니다.

• 사용자 정의 HTTP 헤더

  사용자 정의 HTTP 헤더는 URL을 수집할 때 전송할 HTTP 요청에 포함되는 헤더의 이름과 값의 목록을 가리킵니다. 이 옵션에 헤더의 이름과 값을 입력하면 해당 헤더를 모든 HTTP 요청 메시지에 추가하게 됩니다. 추가하기 버튼을 클릭하여 하나 이상의 헤더를 추가하고 휴지통 아이콘을 클릭하여 삭제할 수 있습니다.

  이 옵션에는 HTTP 요청에 반드시 필요한 헤더를 입력해야 합니다. 이로 인해 브라우저에 프록시를 설정하므로 수집 속도가 느려질 수 있습니다.

  Cookie 헤더를 제외하고 동일한 이름의 헤더를 여러 개 입력한 경우 그 중 하나만 적용됩니다. 따라서 여러 값을 입력해야 하는 경우 헤더 값을 ;로 구분하여 입력하세요. 같은 이름의 헤더가 이미 있는 경우 해당 헤더를 지우고 커스텀 헤더가 추가됩니다. 커스텀 헤더를 사용하려면 분석 대상 URL의 호스트가 localhost 또는 127.0.0.1로 설정되면 안됩니다. 로컬에 있는 웹 애플리케이션을 분석하려는 경우 로컬 IP 주소를 입력해야 합니다.

• URL 수집 깊이

  URL 수집 깊이는 수집할 URL이 시작 URL에서부터 얼마나 멀리 떨어져 있는지를 의미하며 high, medium, low로 구분합니다. URL이 멀수록 시작 URL에서 특정 URL에 도달하기 위해 페이지 이동 등 수행해야 하는 최소한의 동작이 많아집니다.(기본값: medium)

  이 옵션을 high로 설정하면 시작 URL에서부터 멀리 있는 URL까지도 수집하게 되지만 수집하는 시간이 오래 걸립니다. 이 옵션을 low로 설정하면 프로젝트에서 URL을 수집하는 시간은 짧아지지만 멀리 있는 URL은 수집하지 않게 됩니다.

• DOM 수집 깊이

  DOM 수집 깊이는 수집할 DOM이 동일한 URL에서 생성된 첫 번째 DOM으로부터 얼마나 멀리 떨어져 있는지를 의미하며 high, medium, low로 구분합니다. DOM이 멀수록 첫 번째 DOM에서 동일한 URL의 특정 DOM에 도달하기 위해 수행해야 하는 최소한의 동작이 많아집니다.(기본값: medium)

  이 옵션을 high로 설정하면 URL로 이동할 때 생성되는 첫 DOM에서부터 멀리 있는 DOM까지도 수집하게 되지만 수집하는 시간이 오래 걸립니다. 이 옵션을 low로 설정하면 프로젝트에서 DOM을 수집하는 시간은 짧아지지만 멀리 있는 DOM은 수집하지 않게 됩니다.

  • 이벤트 대기 시간

  이벤트 대기 시간은 이벤트를 수행할 때마다 이벤트 수행 결과가 DOM에 반영되기를 기다리는 시간을 가리킵니다. 0 이상 5000 이하의 숫자를 입력할 수 있으며 옵션을 입력하지 않은 경우 기본값은 300입니다.(단위: 밀리초, 기본값: 300)

• 요청 횟수

  HTTP 요청 횟수는 URL을 수집할 때 1초에 전송할 수 있는 HTTP 요청의 개수를 가리킵니다. -1 이상 10000 이하의 숫자를 입력할 수 있으며 옵션을 입력하지 않는 경우 기본값은 -1이며 이 경우에 전송할 수 있는 HTTP 요청의 개수를 제한하지 않게 됩니다.(단위: 개, 기본값: -1)

  이 옵션에 입력된 값이 클수록 1초에 전송할 수 있는 HTTP 요청의 개수가 늘어나서 URL을 수집하는 속도가 빨라지지만 트래픽량이 늘어나 분석 대상 웹 애플리케이션 서버에 부하도 늘어날 수 있습니다. 이 옵션에 입력된 값이 적을수록 트래픽량이 낮아져 분석 대상 웹 애플리케이션 서버의 부하도 줄어들지만 URL을 수집하는 속도가 늦어집니다.

• HTTP 클라이언트 대기 시간

  HTTP 클라이언트 대기 시간은 HTTP 클라이언트가 분석을 수행하기 위해 웹 서버에 연결하고, HTTP 요청을 보내고, HTTP 응답을 받는 과정에서 지연이 발생했을 때 기다리는 최대 시간을 가리킵니다. 0 이상 30000 이하의 숫자를 입력할 수 있으며 옵션을 입력하지 않은 경우 기본값은 3000 입니다.(단위: 밀리초, 기본값: 3000)

  이 옵션에 입력된 값이 클수록 웹 서버와의 네트워크 연결 상태가 좋지 않아 지연이 발생한 경우에도 분석이 정상적으로 진행됩니다. 단, 웹 서버와의 연결 끊김이 지속적으로 발생하면 분석 시간이 늘어날 가능성이 높습니다. 이 옵션에 입력된 값이 적을수록 분석 속도는 빨라지지만 웹 서버와의 네트워크 연결 상태가 좋지 않아서 지연이 발생한 경우 URL을 분석하지 못할 가능성이 있습니다.

분석 목록 컴포넌트

분석을 확인할 때 사용할 수 있는 UI 컴포넌트입니다. 분석 목록에서 항목을 클릭하면 좀 더 자세한 요약 정보를 확인할 수 있습니다.

1. 다음과 같은 코드를 사용하여 Sparrow On-Demand UI Kit 클라이언트를 생성하세요.

import { useState } from "react";
import {
  OndemandClient,
  OndemandClientConfig,
  SparrowAnalysisRequest,
  SparrowOnDemandProvider,
  SparrowAnalysisResult,
} from "@sparrowai/ondemand-uikit";
import "@sparrowai/ondemand-uikit/style.css";

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

  
  const [client] = useState<OndemandClient>(() => {
    return new OndemandClient(config);
  });

  return (
    <SparrowOnDemandProvider client={client}>
      <SparrowAnalysisResult />
    </SparrowOnDemandProvider>
  );
}

Tip: 아래의 속성을 적절히 변경하세요.

apiKey API 요청에서 인증에 사용하기 위해 Sparrow On-Demand에서 발급 받은 토큰(API_KEY)입니다.

2. 애플리케이션을 실행하고 분석 목록 컴포넌트가 올바르게 표시되는지 확인하세요.

Tip: 분석 목록에는 입력한 API 키로 접근할 수 있는 모든 분석이 표시됩니다. 분석이 없는 경우 분석 요청 컴포넌트를 사용하여 분석을 요청하세요.

3. 분석 목록에서 항목을 클릭하고 분석 상세 정보를 확인하세요.

---