[!IMPORTANT] KubeClarity는 더 이상 사용되지 않으며 openclarity/openclarity로 대체되었습니다.

자세한 내용은 릴리스 성명서를 확인하세요.

이 프로젝트는 업데이트를 받지 않습니다. 마이그레이션을 권장합니다.

KubeClarity는 컨테이너 이미지 및 파일 시스템의 소프트웨어 자재 명세서(SBOM) 및 취약점 탐지 및 관리를 위한 도구입니다. 향상된 소프트웨어 공급망 보안을 위해 런타임 K8s 클러스터와 CI/CD 파이프라인을 모두 스캔합니다.

왜?

SBOM 및 취약점 탐지 과제

효과적인 취약점 스캔을 위해서는 정확한 소프트웨어 자재 명세서(SBOM) 탐지가 필요합니다:
- 다양한 프로그래밍 언어 및 패키지 관리자
- 다양한 OS 배포판
- 패키지 종속성 정보는 일반적으로 빌드 시 제거됩니다
최고의 스캐너/SBOM 분석기는 무엇인가요?
무엇을 스캔해야 할까요: Git 리포지토리, 빌드, 컨테이너 이미지 또는 런타임?
각 스캐너/분석기는 자체 형식을 가지고 있습니다. 결과를 어떻게 비교할 수 있나요?
발견된 SBOM 및 취약점을 어떻게 관리하나요?
새로 발견된 취약점이 내 애플리케이션에 어떤 영향을 미치나요?

해결책

취약점 스캔을 두 단계로 분리:
- SBOM 생성을 위한 콘텐츠 분석
- 취약점에 대한 SBOM 스캔
플러그형 인프라 생성:
- 여러 콘텐츠 분석기를 병렬로 실행
- 여러 취약점 스캐너를 병렬로 실행
KubeClarity CLI를 사용하여 다른 CI 단계 간 결과 스캔 및 병합
배포 후 발견된 취약점 탐지를 위한 런타임 K8s 스캔
스캔된 리소스(이미지/디렉토리)를 정의된 애플리케이션 아래에 그룹화하여 객체 트리 종속성(애플리케이션, 리소스, 패키지, 취약점)을 탐색합니다.

기능

대시보드
- 심각도별 수정 가능한 취약점
- 상위 5개 취약 요소(애플리케이션, 리소스, 패키지)
- 신규 취약점 동향
- 라이선스 유형별 패키지 개수
- 프로그래밍 언어별 패키지 개수
- 일반 카운터
애플리케이션
- K8s 런타임에서 자동 애플리케이션 탐지
- 애플리케이션 생성/편집/삭제
- 애플리케이션별 관련 항목 탐색:
  - 리소스(이미지/디렉토리)
  - 패키지
  - 취약점
  - 리소스에서 사용 중인 라이선스
애플리케이션 리소스(이미지/디렉토리)
- 리소스별 관련 항목 탐색:
  - 애플리케이션
  - 패키지
  - 취약점
패키지
- 패키지별 관련 항목 탐색:
  - 애플리케이션
  - 리소스 및 탐지 SBOM 분석기의 연결 가능한 목록
  - 취약점
취약점
- 취약점별 관련 항목 탐색:
  - 애플리케이션
  - 리소스
  - 탐지 스캐너 목록
K8s 런타임 스캔
- 요청 시 또는 예약된 스캔
- 대상 네임스페이스 자동 탐지
- 영향을 받는 요소(애플리케이션, 리소스, 패키지, 취약점)별 스캔 진행 상황 및 결과 탐색
- CIS Docker 벤치마크
CLI(CI/CD)
- 여러 통합 콘텐츠 분석기(Syft, cyclonedx-gomod)를 사용한 SBOM 생성
- 여러 통합 스캐너(Grype, Dependency-track)를 사용한 SBOM/이미지/디렉토리 취약점 스캔
- 다양한 CI/CD 단계 간 SBOM 및 취약점 병합
- 결과를 KubeClarity 백엔드로 내보내기
API
- KubeClarity의 API는 여기에서 확인할 수 있습니다.

통합 SBOM 생성기 및 취약점 스캐너

KubeClarity 콘텐츠 분석기는 다음 SBOM 생성기와 통합됩니다:

KubeClarity 취약점 스캐너는 다음 스캐너와 통합됩니다:

아키텍처

시작하기

KubeClarity 백엔드

Helm을 사용하여 설치:

Helm 리포지토리 추가 ```shell helm repo add kubeclarity https://openclarity.github.io/kubeclarity

KubeClarity 기본 차트 값 저장

helm show values kubeclarity/kubeclarity > values.yaml

values.yaml의 구성을 확인하고 필요한 경우 필요한 값을 업데이트하세요. 지원되는 SBOM 생성기 및 취약점 스캐너를 활성화하고 구성하려면 Helm 값의 "vulnerability-scanner" 섹션 아래 "analyzer" 및 "scanner" 구성을 확인하십시오.
Helm으로 KubeClarity 배포 ```shell helm install --values values.yaml --create-namespace kubeclarity kubeclarity/kubeclarity -n kubeclarity

또는 OpenShift Restricted SCC 호환 설치를 위해: ```shell helm install --values values.yaml --create-namespace kubeclarity kubeclarity/kubeclarity -n kubeclarity --set global.openShiftRestricted=true
--set kubeclarity-postgresql.securityContext.enabled=false --set kubeclarity-postgresql.containerSecurityContext.enabled=false
--set kubeclarity-postgresql.volumePermissions.enabled=true --set kubeclarity-postgresql.volumePermissions.securityContext.runAsUser="auto"
--set kubeclarity-postgresql.shmVolume.chmod.enabled=false

3. KubeClarity UI로 포트 포워드:   ```shell
kubectl port-forward -n kubeclarity svc/kubeclarity-kubeclarity 9999:8080

브라우저에서 KubeClarity UI를 엽니다: http://localhost:9999/

참고
KubeClarity는 다음과 같은 K8s 권한이 필요합니다:

Helm을 사용한 제거:

Helm 제거 ```shell helm uninstall kubeclarity -n kubeclarity
리소스 정리

기본적으로 Helm은 StatefulSets에 대한 PVC와 PV를 제거하지 않습니다. 다음 명령어를 실행하여 모두 삭제하십시오:
```
kubectl delete pvc -l app.kubernetes.io/instance=kubeclarity -n kubeclarity
```

데모 데이터로 로컬에서 빌드 및 실행

UI 및 백엔드 빌드 후 로컬에서 백엔드 시작 (2가지 옵션):
1. Docker 사용:
  1. UI 및 백엔드 빌드 (이미지 태그는 VERSION을 사용하여 설정됩니다):
```
VERSION=test make docker-backend
```
  2. 데모 데이터를 사용하여 백엔드 실행:
```
docker run -p 8080:8080 -e FAKE_RUNTIME_SCANNER=true -e FAKE_DATA=true -e ENABLE_DB_INFO_LOGS=true -e DATABASE_DRIVER=LOCAL ghcr.io/openclarity/kubeclarity:test run
```
2. 로컬 빌드:
  1. UI 및 백엔드 빌드
```
make ui && make backend
```
  2. 빌드된 사이트 복사:
```
cp -r ./ui/build ./site
```
  3. 데모 데이터를 사용하여 로컬에서 백엔드 실행:
```
FAKE_RUNTIME_SCANNER=true DATABASE_DRIVER=LOCAL FAKE_DATA=true ENABLE_DB_INFO_LOGS=true ./backend/bin/backend run
```
브라우저에서 KubeClarity UI 열기: http://localhost:8080/

CLI

KubeClarity에는 로컬에서 실행할 수 있는 CLI가 포함되어 있으며, 특히 CI/CD 파이프라인에 유용합니다. 이 CLI를 사용하면 이미지와 디렉터리를 분석하여 SBOM을 생성하고 취약점을 스캔할 수 있습니다. 결과는 KubeClarity 백엔드로 내보낼 수 있습니다.

설치

Binary Distribution

운영 체제에 맞는 릴리스 배포판을 릴리스 페이지에서 다운로드하세요.

kubeclarity-cli 바이너리 압축을 풀고 PATH에 추가하면 준비 완료입니다!

Docker Image

Docker 이미지는 ghcr.io/openclarity/kubeclarity-cli에서 사용할 수 있으며, 사용 가능한 태그 목록은 여기에서 확인할 수 있습니다.

Local Compilation

``` make cli ``` Copy `./cli/bin/cli`를 `kubeclarity-cli`라는 이름으로 PATH에 복사하세요.

SBOM 생성```

kubeclarity-cli analyze <image/directory name> --input-type <dir|file|image(default)> -o

예시:```
kubeclarity-cli analyze --input-type image nginx:latest -o nginx.sbom

선택적으로 사용할 콘텐츠 분석기 목록을 ANALYZER_LIST 환경 변수를 사용하여 공백으로 구분하여 구성할 수 있습니다 (예: ANALYZER_LIST="<analyzer 1 name> <analyzer 2 name>")

예시:``` ANALYZER_LIST="syft gomod" kubeclarity-cli analyze --input-type image nginx:latest -o nginx.sbom

### 취약점 스캔

사용법:```
kubeclarity-cli scan <image/sbom/directoty/file name> --input-type <sbom|dir|file|image(default)> -f <output file>

예시:``` kubeclarity-cli scan nginx.sbom --input-type sbom

사용할 취약점 스캐너 목록을 선택적으로 `SCANNERS_LIST` 환경 변수를 사용하여 공백으로 구분하여 구성할 수 있습니다 (예: `SCANNERS_LIST="<Scanner1 name> <Scanner2 name>"`)

예시:```
SCANNERS_LIST="grype trivy" kubeclarity-cli scan nginx.sbom --input-type sbom

KubeClarity 백엔드로 결과 내보내기

CLI 결과를 KubeClarity 백엔드로 내보내려면 KubeClarity 백엔드에서 정의한 애플리케이션 ID를 사용해야 합니다. 애플리케이션 ID는 UI의 Applications 화면에서 찾거나 KubeClarity API를 통해 확인할 수 있습니다.

SBOM 내보내기```

The SBOM can be exported to KubeClarity backend by setting the BACKEND_HOST env variable and the -e flag.

Note: Until TLS is supported, BACKEND_DISABLE_TLS=true should be set.

BACKEND_HOST= BACKEND_DISABLE_TLS=true kubeclarity-cli analyze --application-id -e -o

For example:

BACKEND_HOST=localhost:9999 BACKEND_DISABLE_TLS=true kubeclarity-cli analyze nginx:latest --application-id 23452f9c-6e31-5845-bf53-6566b81a2906 -e -o nginx.sbom

#### 취약점 스캔 결과 내보내기```
# The vulnerability scan result can be exported to KubeClarity backend by setting the BACKEND_HOST env variable and the -e flag.
# Note: Until TLS is supported, BACKEND_DISABLE_TLS=true should be set.

BACKEND_HOST=<KubeClarity backend address> BACKEND_DISABLE_TLS=true kubeclarity-cli scan <image> --application-id <application ID> -e

# For example:
SCANNERS_LIST="grype" BACKEND_HOST=localhost:9999 BACKEND_DISABLE_TLS=true kubeclarity-cli scan nginx.sbom --input-type sbom  --application-id 23452f9c-6e31-5845-bf53-6566b81a2906 -e

고급 설정

로컬 docker 이미지를 입력으로 사용한 SBOM 생성```

Local docker images can be analyzed using the LOCAL_IMAGE_SCAN env variable

For example:

LOCAL_IMAGE_SCAN=true kubeclarity-cli analyze nginx:latest -o nginx.sbom

## 로컬 도커 이미지를 입력으로 사용한 취약점 스캐닝```
# Local docker images can be scanned using the LOCAL_IMAGE_SCAN env variable

# For example:
LOCAL_IMAGE_SCAN=true kubeclarity-cli scan nginx.sbom

CLI용 비공개 레지스트리 지원

KubeClarity cli는 비공개 레지스트리의 자격 증명을 저장하는 구성 파일을 읽을 수 있습니다.

구성 파일의 레지스트리 섹션 예시:``` registry: auths: - authority: <registry 1> username: <username for registry 1> password: <password for registry 1> - authority: <registry 2> token: <token for registry 2>

권한이 없는 레지스트리 구성 예시: (이 경우 이 인증 정보는 모든 레지스트리에 사용됩니다)```
registry:
  auths:
    - username: <username>
      password: <password>

CLI용 구성 파일 지정```

The default config path is $HOME/.kubeclarity or it can be specified by `--config` command line flag.

kubeclarity <scan/analyze> --config

For example:

kubeclarity scan registry/nginx:private --config $HOME/own-kubeclarity-config

## K8s 런타임 스캔을 위한 비공개 레지스트리 지원

Kubeclarity는 인증을 위해 google/go-containerregistry의 [k8schain](https://github.com/google/go-containerregistry/tree/main/pkg/authn/k8schain#k8schain)을 사용합니다.
필요한 서비스 자격 증명을 k8schain이 발견할 수 없는 경우, 아래에 설명된 시크릿을 통해 정의할 수 있습니다.

또한, 서비스 자격 증명이 "kubeclarity" 네임스페이스에 위치하지 않은 경우, kubeclarity Deployment에 CREDS_SECRET_NAMESPACE를 설정하십시오.
Helm [차트](https://github.com/openclarity/kubeclarity/blob/HEAD/charts)를 사용할 때, CREDS_SECRET_NAMESPACE는 kubeclarity를 설치한 릴리스 네임스페이스로 설정됩니다.

### Amazon ECR

`AmazonEC2ContainerRegistryFullAccess` 권한을 가진 [AWS IAM 사용자](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console)를 생성합니다.

사용자 자격 증명(`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`)을 사용하여 다음 시크릿을 생성합니다:```
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: ecr-sa
  namespace: kubeclarity
type: Opaque
data:
  AWS_ACCESS_KEY_ID: $(echo -n 'XXXX'| base64 -w0)
  AWS_SECRET_ACCESS_KEY: $(echo -n 'XXXX'| base64 -w0)
  AWS_DEFAULT_REGION: $(echo -n 'XXXX'| base64 -w0)
EOF

참고:

Secret 이름은 ecr-sa여야 합니다.
Secret 데이터 키는 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY 및 AWS_DEFAULT_REGION으로 설정해야 합니다.

Google GCR

Artifact Registry Reader 권한이 있는 Google 서비스 계정을 생성합니다.

서비스 계정 json 파일을 사용하여 다음 Secret을 생성합니다.``` kubectl -n kubeclarity create secret generic --from-file=sa.json gcr-sa

참고:
1. 비밀 이름은 `gcr-sa`여야 합니다.
1. 비밀을 생성할 때 서비스 계정 JSON 파일 이름은 `sa.json`이어야 합니다.
2. KubeClarity는 [애플리케이션 기본 자격 증명](https://developers.google.com/identity/protocols/application-default-credentials)을 사용합니다. 이는 KubeClarity를 GCP에서 실행할 때만 작동합니다.

## CI/CD 단계 간 SBOM 및 취약점 병합```
# Additional SBOM will be merged into the final results when '--merge-sbom' is defined during analysis. The input SBOM can be CycloneDX XML or CyclonDX json format.
# For example:
ANALYZER_LIST="syft" kubeclarity-cli analyze nginx:latest -o nginx.sbom --merge-sbom inputsbom.xml

다양한 SBOM 형식 출력

kubeclarity-cli analyze 명령은 결과 SBOM을 다른 시스템과 통합해야 하는 경우 다른 형식으로 변환할 수 있습니다. 지원되는 형식은 다음과 같습니다:

형식	구성 이름
CycloneDX JSON (기본값)	cyclonedx-json
CycloneDX XML	cyclonedx-xml
SPDX JSON	spdx-json
SPDX Tag Value

WARNING
KubeClarity는 내부적으로 CycloneDX를 처리하며, 다른 형식은 변환을 통해 지원됩니다. 형식 간 비호환성으로 인해 변환 과정에서 데이터 손실이 발생할 수 있으므로, 결과 출력에 모든 필드/정보가 포함된다고 보장할 수 없습니다.

kubeclarity-cli가 기본 형식 외의 다른 형식을 사용하도록 구성하려면, ANALYZER_OUTPUT_FORMAT 환경 변수를 위의 구성 이름과 함께 사용할 수 있습니다:``` ANALYZER_OUTPUT_FORMAT="spdx-json" kubeclarity-cli analyze nginx:latest -o nginx.sbom

## CLI용 원격 스캐너 서버

kubeclarity CLI를 실행하여 취약점을 스캔할 때, CLI는 관련 취약점 데이터베이스를 kubeclarity CLI가 실행되는 위치로 다운로드해야 합니다. CI/CD 파이프라인에서 CLI를 실행하면 실행할 때마다 DB를 다운로드하여 시간과 대역폭을 낭비하게 됩니다. 이러한 이유로 지원되는 여러 스캐너에는 DB 관리 및 아티팩트 스캔을 담당하는 서버가 있는 원격 모드가 있습니다.

> ***참고***
>
> 아래 예시는 각 스캐너에 대한 것이지만, 원격 모드가 아닌 경우와 마찬가지로 함께 실행하도록 결합할 수 있습니다.

### Trivy

Trivy 스캐너는 Trivy 서버를 사용하여 원격 모드를 지원합니다. Trivy 서버는 여기에 문서화된 대로 배포할 수 있습니다: [trivy 클라이언트-서버 모드](https://aquasecurity.github.io/trivy/v0.34/docs/references/modes/client-server/).
Trivy CLI 설치 방법은 다음에서 확인할 수 있습니다: [trivy 설치](https://aquasecurity.github.io/trivy/v0.34/getting-started/installation/).
Aqua 팀은 예제에서 사용할 kubernetes/docker에서 서버를 실행할 수 있는 공식 컨테이너 이미지를 제공합니다.

서버를 시작하려면:```
docker run -p 8080:8080 --rm aquasec/trivy:0.41.0 server --listen 0.0.0.0:8080

서버를 사용하여 스캔을 실행하려면:``` SCANNERS_LIST="trivy" SCANNER_TRIVY_SERVER_ADDRESS="http://:8080" ./kubeclarity_cli scan --input-type sbom nginx.sbom

trivy 서버는 또한 토큰 기반 인증을 제공하여 trivy 서버 인스턴스의 무단 사용을 방지합니다. 서버를 추가 플래그로 실행하여 활성화할 수 있습니다:```
docker run -p 8080:8080 --rm aquasec/trivy:0.41.0 server --listen 0.0.0.0:8080 --token mytoken

토큰을 스캐너에 전달하고:``` SCANNERS_LIST="trivy" SCANNER_TRIVY_SERVER_ADDRESS="http://:8080" SCANNER_TRIVY_SERVER_TOKEN="mytoken" ./kubeclarity_cli scan --input-type sbom nginx.sbom

### Grype

Grype는 원격 모드를 지원합니다. [grype-server](https://github.com/portshift/grype-server)를 사용하여
RESTful grype 래퍼로서 SBOM을 받아 해당 SBOM에 대한 grype 스캔 결과를 반환하는 API를 제공합니다.
Grype-server는 컨테이너 이미지로 제공되므로 kubernetes 또는 docker standalone에서 실행할 수 있습니다.

서버를 시작하려면:```
docker run -p 9991:9991 --rm gcr.io/eticloud/k8sec/grype-server:v0.1.5

서버를 사용하여 스캔을 실행하려면:``` SCANNERS_LIST="grype" SCANNER_GRYPE_MODE="remote" SCANNER_REMOTE_GRYPE_SERVER_ADDRESS=":9991" SCANNER_REMOTE_GRYPE_SERVER_SCHEMES="https" ./kubeclarity_cli scan --input-type sbom nginx.sbom

If Grype server is deployed with TLS you can override the default URL scheme like:
Grype 서버가 TLS로 배포된 경우 기본 URL 스킴을 다음과 같이 재정의할 수 있습니다:```
SCANNERS_LIST="grype" SCANNER_GRYPE_MODE="remote" SCANNER_REMOTE_GRYPE_SERVER_ADDRESS="<grype server address>:9991" SCANNER_REMOTE_GRYPE_SERVER_SCHEMES="https" ./kubeclarity_cli scan --input-type sbom nginx.sbom

Dependency Track

예시 구성은 여기를 참조하세요.

제한 사항

Docker Image Manifest V2, Schema 2를 지원합니다 (https://docs.docker.com/registry/spec/manifest-v2-2/). 이전 버전은 스캔에 실패합니다.

로드맵

추가 콘텐츠 분석기(SBOM generators)와 통합
추가 취약점 스캐너와 통합
UI 내 CIS Docker 벤치마크
Cosign을 사용한 이미지 서명
Cosign 및 in-toto를 사용한 CI/CD 메타데이터 서명 및 증명 (공급망 보안)
시스템 설정 및 사용자 관리

기여하기

풀 리퀘스트와 버그 리포트를 환영합니다.

큰 변경 사항은 먼저 GitHub에 Issue를 생성하여 제안된 변경 사항과 가능한 영향을 논의해 주세요.

자세한 내용은 이 프로젝트의 기여 가이드라인을 참조하세요.

라이선스

Apache License, Version 2.0

CREDS_SECRET_NAMESPACE(default: kubeclarity)에서 시크릿 읽기	프라이빗 이미지 리포지토리를 스캔하기 위한 이미지 풀 시크릿을 구성할 수 있도록 합니다.
KubeClarity 배포 네임스페이스에서 ConfigMap 읽기	스캐너 작업의 구성된 템플릿을 가져오는 데 필요합니다.
클러스터 범위에서 파드 나열	스캔해야 할 대상 파드를 계산하는 데 필요합니다.
네임스페이스 나열	K8s 런타임 스캔 UI에서 스캔할 대상 네임스페이스를 가져오는 데 필요합니다.
클러스터 범위에서 작업 생성 및 삭제	해당 네임스페이스에서 대상 파드를 스캔할 작업을 관리하는 데 필요합니다.

kubeclarity

인기

목차

왜?

SBOM 및 취약점 탐지 과제

해결책

기능

통합 SBOM 생성기 및 취약점 스캐너

아키텍처

시작하기

KubeClarity 백엔드

Helm을 사용하여 설치:

Helm을 사용한 제거:

데모 데이터로 로컬에서 빌드 및 실행

CLI

설치

SBOM 생성```

KubeClarity 백엔드로 결과 내보내기

SBOM 내보내기```

The SBOM can be exported to KubeClarity backend by setting the BACKEND_HOST env variable and the -e flag.

Note: Until TLS is supported, BACKEND_DISABLE_TLS=true should be set.

For example:

고급 설정

로컬 docker 이미지를 입력으로 사용한 SBOM 생성```

Local docker images can be analyzed using the LOCAL_IMAGE_SCAN env variable

For example:

CLI용 비공개 레지스트리 지원

CLI용 구성 파일 지정```

The default config path is $HOME/.kubeclarity or it can be specified by --config command line flag.

kubeclarity <scan/analyze> --config

For example:

Google GCR

다양한 SBOM 형식 출력

Dependency Track

제한 사항

로드맵

기여하기

라이선스

The default config path is $HOME/.kubeclarity or it can be specified by `--config` command line flag.