Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions .github/workflows/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,22 +29,22 @@ caller는 자동 실행에서 `source_ref: ${{ github.sha }}`를 전달합니다
- Trivy 취약점·image secret 검사
- CycloneDX SBOM 생성
- GHCR push와 image digest 추출
- Runtime artifact와 Challenge Registry publish document 생성
- `artifact-v2.json`과 수동 검증용 `registry-publish.json` 생성
- Actions Summary에 컨테이너별 GHCR digest 표시
- Build/Pull, Trivy Scan, GHCR Push와 합계 시간 측정
- publish bundle을 90일 보관하고 artifact 이름을 caller output으로 제공
- 설정된 경우 publish document를 Challenge Registry HTTPS API에 등록
- 설정된 경우 SSM을 통해 Secure Provisioner API로 K3s 생성·삭제 smoke test

승인된 `main` 실행만 이 workflow를 호출해 image와 publish bundle을 발행합니다.
출제자 branch와 PR은 `challenge-branch-validation.yml`을 호출합니다.

Challenge Registry 등록은 `publish_registry: true`,
`CHALLENGE_REGISTRY_URL`, `CHALLENGE_REGISTRY_TOKEN`이 모두 설정된 경우에만
실행합니다. URL과 token은 임의 실행 입력이 아닌 GitHub Secret으로 관리합니다.
기본값은 비활성화이며 Backend DB, Scheduler와 Broker를 workflow가 직접
조작하지 않습니다. K3s smoke test도 Runtime API를 거치며 Kubernetes resource를
직접 생성하지 않습니다.
성공한 실행은 `-publish-bundle` suffix의 Actions artifact를 남깁니다.
`artifact-v2.json`은 Backend poller가 자동 수집하는 공식 입력이고,
`registry-publish.json`은 같은 artifact를 감싼 수동 API 검증용 wrapper입니다.
workflow와 caller는 Backend base URL 또는 service token을 사용하지 않으며,
Backend poller가 수집, challenge 매핑, release 등록, 중복 처리를 수행합니다.
Backend/admin이 active release 전환과 롤백을 수행합니다. K3s smoke test는
Runtime API를 거치며 Kubernetes resource를 직접 생성하지 않습니다.

### `pipeline-self-test.yml`

Expand Down
73 changes: 0 additions & 73 deletions .github/workflows/challenge-supply-chain.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,6 @@ on:
required: false
default: true
type: boolean
publish_registry:
description: 검증된 revision을 Challenge Registry API에 등록할지 여부
required: false
default: false
type: boolean
enable_k3s_smoke_deploy:
description: Secure Provisioner API를 통한 AWS K3s 임시 배포 검증 실행 여부
required: false
Expand Down Expand Up @@ -55,10 +50,6 @@ on:
# 이전 caller 호환용입니다. Runtime smoke에서는 사용하지 않습니다.
GHCR_PULL_SECRET_ARN:
required: false
CHALLENGE_REGISTRY_TOKEN:
required: false
CHALLENGE_REGISTRY_URL:
required: false
permissions:
contents: read

Expand Down Expand Up @@ -414,70 +405,6 @@ jobs:
if-no-files-found: error
retention-days: 90

publish-registry:
needs:
- aggregate
if: >-
inputs.publish_images &&
inputs.publish_registry &&
needs.aggregate.result == 'success'
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: 발행 bundle 가져오기
uses: actions/download-artifact@v4
with:
name: ${{ needs.aggregate.outputs.publish_bundle_name }}
path: dist

- name: Challenge Registry 연결 설정 검증
env:
REGISTRY_API_URL: ${{ secrets.CHALLENGE_REGISTRY_URL }}
REGISTRY_TOKEN: ${{ secrets.CHALLENGE_REGISTRY_TOKEN }}
run: |
case "$REGISTRY_API_URL" in
https://*) ;;
*) echo "registry_api_url은 HTTPS URL이어야 합니다" >&2; exit 1 ;;
esac
if [ -z "$REGISTRY_TOKEN" ]; then
echo "CHALLENGE_REGISTRY_TOKEN이 필요합니다" >&2
exit 1
fi
if [[ "$REGISTRY_TOKEN" == *$'\n'* || "$REGISTRY_TOKEN" == *$'\r'* ]]; then
echo "CHALLENGE_REGISTRY_TOKEN에 줄바꿈을 사용할 수 없습니다" >&2
exit 1
fi

- name: Challenge Registry revision 등록
env:
REGISTRY_API_URL: ${{ secrets.CHALLENGE_REGISTRY_URL }}
REGISTRY_TOKEN: ${{ secrets.CHALLENGE_REGISTRY_TOKEN }}
run: |
challenge_slug="$(jq -r '.challenge_slug' dist/registry-publish.json)"
revision="$(jq -r '.revision' dist/registry-publish.json)"
payload_sha256="$(sha256sum dist/registry-publish.json | cut -d ' ' -f 1)"
idempotency_key="${GITHUB_REPOSITORY_ID}:${challenge_slug}:${revision}:${payload_sha256}"
curl --fail-with-body \
--retry 3 \
--retry-all-errors \
--connect-timeout 5 \
--max-time 30 \
--request POST \
--header "Authorization: Bearer ${REGISTRY_TOKEN}" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: ${idempotency_key}" \
--data-binary @dist/registry-publish.json \
--output dist/registry-response.txt \
"$REGISTRY_API_URL"
{
echo "## Challenge Registry 등록 결과"
echo
echo "- 문제: \`${challenge_slug}\`"
echo "- revision: \`${revision}\`"
echo "- 상태: \`ACCEPTED\`"
} >> "$GITHUB_STEP_SUMMARY"

k3s-smoke-deploy:
needs:
- validate
Expand Down
2 changes: 0 additions & 2 deletions .github/workflows/pipeline-self-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,6 @@ jobs:
challenge_path: tests/fixtures/info-valid
revision: ${{ github.run_number }}
devsecops_ref: ${{ github.sha }}
publish_registry: false
enable_k3s_smoke_deploy: false
secrets: inherit

Expand Down Expand Up @@ -80,6 +79,5 @@ jobs:
challenge_path: tests/fixtures/koth-template
revision: ${{ github.run_number }}
devsecops_ref: ${{ github.sha }}
publish_registry: false
enable_k3s_smoke_deploy: false
secrets: inherit
59 changes: 39 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,9 @@ Challenge Repo
→ CycloneDX SBOM 생성
→ OCI Registry에 commit SHA tag로 push
→ OCI digest 추출
→ Runtime artifact + Registry publish document 생성
→ 선택적으로 Challenge Registry API에 revision 등록
→ `artifact-v2.json`과 수동 검증용 `registry-publish.json` 생성
→ `-publish-bundle` Actions artifact 보관
→ Backend poller가 artifact를 수집해 release 등록
```

Platform 실행 흐름은 다음과 같습니다.
Expand Down Expand Up @@ -86,6 +87,11 @@ deployment:
image: postgres:16
ports: [5432]
expose: false
internal_connections:
- source_container: web
destination_container: db
protocol: TCP
port: 5432
healthcheck:
container: web
port: 9090
Expand All @@ -103,6 +109,11 @@ deployment:
- `build`는 문제 디렉터리 내부의 Docker build context만 가리킬 수 있습니다.
- 외부 `image`는 `latest`나 암묵적 tag를 사용할 수 없으며 명시적 non-latest tag 또는 digest가 필요합니다.
- `expose: true`인 컨테이너의 포트만 참가자에게 공개합니다.
- 컨테이너 간 통신은 `internal_connections`에 TCP 방향과 목적지 포트를
명시합니다. 선언하지 않은 통신은 Runtime NetworkPolicy가 차단합니다.
- 출제자는 raw Kubernetes `NetworkPolicy`를 입력하지 않습니다. CI는 문제
category를 `WEB` 또는 `PWN` `isolation_profile`로 정규화하고 Runtime이
승인된 정책을 생성합니다.
- `resource_profile`은 문제의 모든 컨테이너를 합산한 값입니다.
- `flag`는 존재 여부만 검증하며 로그, output, artifact에 기록하지 않습니다.
- `deployment`가 없는 정적 문제는 Docker build와 image 발행을 수행하지 않습니다.
Expand Down Expand Up @@ -141,7 +152,6 @@ Docker build context와 secret을 검사하고 image를 build한 뒤 Trivy와 Cy
- `revision`: 새 Challenge Registry revision
- `devsecops_ref`: 공급망 도구 version, 기본값 `main`
- `publish_images`: 검사한 image를 GHCR에 발행하고 publish bundle을 생성할지 여부, 기본값 `true`
- `publish_registry`: Challenge Registry API 등록 여부, 기본값 `false`
- `enable_k3s_smoke_deploy`: Secure Provisioner API 경유 임시 K3s 배포 검증 여부, 기본값 `false`
- `runtime_target_id`: Secure Provisioner Registry의 K3s target ID

Expand All @@ -151,8 +161,10 @@ Docker build context와 secret을 검사하고 image를 build한 뒤 Trivy와 Cy

출제자 branch와 PR 검증에서는 `publish_images: false`를 사용하고 Secret을 전달하지
않습니다. 이 모드는 Docker build, Gitleaks, Trivy와 SBOM 생성까지만 수행합니다.
GHCR push, Challenge Registry 등록과 Runtime smoke는 승인된 `main` 실행에서만
활성화합니다.
GHCR push, publish bundle 생성과 Runtime smoke는 승인된 `main` 실행에서만
활성화합니다. release 등록은 Backend poller가 성공한 Actions artifact를 수집해
처리하므로 caller와 reusable workflow에 Backend URL 또는 service token을 두지
않습니다.

출력 artifact:

Expand Down Expand Up @@ -182,7 +194,7 @@ GitHub runner 대기 시간과 job 준비 시간은 포함하지 않습니다.
최종 image 경로:

```text
ghcr.io/<owner>/challenges/<challenge_slug>/<container>@sha256:<digest>
ghcr.io/msg-ctf/challenges/<challenge_slug>/<container>@sha256:<digest>
```

`latest`는 생성하지 않습니다.
Expand All @@ -196,35 +208,42 @@ ghcr.io/<owner>/challenges/<challenge_slug>/<container>@sha256:<digest>
healthcheck 포트와 `resource_profile`을 검증한 뒤 다음 경로로 발행합니다.

```text
ghcr.io/<owner>/challenges/<koth_slug>/service@sha256:<digest>
ghcr.io/msg-ctf/challenges/<koth_slug>/service@sha256:<digest>
```

`prob/for_organizer/docker-compose.yml`은 출제자 로컬 테스트용입니다. GHCR에는
`info.yaml`의 `deployment.containers`에 선언된 컨테이너만 발행하므로 Compose의
보조 `checker`는 자동 발행하지 않습니다.

## Atomic Publish
## Publish Bundle과 Backend poller

`artifact-v2.json`은 Backend poller의 자동 수집과 Runtime이 공통으로 사용하는
공식 입력이며, digest 고정 workload입니다. `registry-publish.json`은 같은
artifact를 감싼 수동 API 검증용 wrapper로만 보관합니다.

`artifact-v2.json`은 Runtime이 읽을 digest workload입니다. `registry-publish.json`은 Challenge Registry의 원자적 revision 등록 API가 소비할 자료입니다.
두 파일에는 `revision`과 같은 값인 `registry_revision`, `isolation_profile`,
`workload.containers[]`가 포함됩니다. 모든 최종 image는
`ghcr.io/msg-ctf/challenges/<slug>/<container>@sha256:<digest>` 형식만 허용하며
tag와 `latest`는 발행 자료 생성 단계에서 거절합니다.

발행 조건:

- 모든 container image가 존재합니다.
- 모든 image가 digest로 고정돼 있습니다.
- Gitleaks와 Trivy 검사가 통과했습니다.
- 모든 container의 CycloneDX SBOM이 생성됐습니다.
- 위 조건을 모두 만족해야 active revision 전환을 요청합니다.
- 위 조건을 모두 만족한 bundle만 Backend poller 수집 대상입니다.

`publish_registry: true`이면 workflow가 검증된 `registry-publish.json`을
`CHALLENGE_REGISTRY_URL` secret에 설정된 HTTPS API로 `POST`합니다. 인증에는
`CHALLENGE_REGISTRY_TOKEN` secret을 사용하고, 문제, revision, 요청 body SHA-256을
조합한 `Idempotency-Key`를 전달합니다. API 오류는 성공으로 처리하지 않으며
Registry 등록 job이 실패합니다.
DevSecOps는 `artifact-v2.json`과 GHCR digest image를 발행하고, Backend poller는
`-publish-bundle` artifact 수집, challenge 매핑, release 등록, 동일
`registry_revision`의 중복 처리를 소유합니다. Backend/admin은 active release
전환과 롤백을 소유합니다. Runtime/Secure Provisioner는 active workload의 K3s
배포와 정리를 소유합니다. 혼합 public/private port는 Runtime DTO가 확정될
때까지 손실 변환하지 않습니다.

이 기능은 Backend의 등록 API가 준비될 때까지 기본적으로 비활성화합니다. CI는
Backend DB를 직접 수정하지 않고 API 계약만 사용합니다. 선택형 K3s smoke job만
SSM을 통해 Secure Provisioner API를 호출하며 Scheduler와 Broker의 운영 흐름은
직접 호출하지 않습니다.
Backend 운영 환경의 `RELEASE_POLL_REPO`와 `RELEASE_POLL_GITHUB_TOKEN`은 Backend
팀이 관리합니다. CI는 Backend DB, Scheduler 또는 Broker를 직접 조작하지 않으며,
선택형 K3s smoke job만 SSM으로 Secure Provisioner API를 호출합니다.

## Runtime K3s Smoke

Expand Down Expand Up @@ -262,7 +281,7 @@ K3s는 향후 containerd mirror 설정을 통해 내부 OCI mirror를 사용할
사전 pull, mirror 또는 별도 Registry 도입은 MVP 이후 결정하며, 이 경우에도
Runtime에는 digest 고정 reference만 전달합니다.

신규 아키텍처 기준 공급망은 `info.yaml`, 멀티 컨테이너, digest, SBOM, publish bundle을 지원합니다. Challenge Registry API는 Backend endpoint가 준비된 뒤 활성화하고, Runtime 배포 smoke는 Secure Provisioner API를 경유합니다. OCI mirror와 Terraform/Ansible 인프라는 각 담당 팀의 계약에 맞춰 통합 테스트합니다.
신규 아키텍처 기준 공급망은 `info.yaml`, 멀티 컨테이너, digest, SBOM, publish bundle을 지원합니다. Backend poller가 Actions artifact를 수집해 release를 등록하고, Runtime 배포 smoke는 Secure Provisioner API를 경유합니다. OCI mirror와 Terraform/Ansible 인프라는 각 담당 팀의 계약에 맞춰 통합 테스트합니다.

Windows container는 Linux image와 같은 build job에서 처리하지 않습니다.
Windows runner, node pool, Runtime 및 Registry 계약이 확정된 뒤 별도 workflow로
Expand Down
40 changes: 26 additions & 14 deletions ci/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ DevSecOps는 참가자 instance scheduling, target 선택, Kubernetes manifest
- Dockerfile 존재 여부
- port 범위
- healthcheck container·port·path
- 문제 category에서 결정한 `WEB | PWN` isolation profile
- `internal_connections`의 source·destination·TCP 목적지 포트
- raw Kubernetes NetworkPolicy 입력 금지
- CPU, memory, ephemeral storage 값

검증 결과에는 `flag`가 포함되지 않습니다.
Expand Down Expand Up @@ -65,13 +68,13 @@ Git 이력에서 secret이 발견되면 해당 credential을 폐기·회전하
검사 통과 image만 다음 경로로 push합니다.

```text
ghcr.io/<owner>/challenges/<challenge_slug>/<container>:<commit_sha>-<run_id>-<run_attempt>
ghcr.io/msg-ctf/challenges/<challenge_slug>/<container>:<commit_sha>-<run_id>-<run_attempt>
```

Runtime에 전달하는 값은 다음과 같습니다.

```text
ghcr.io/<owner>/challenges/<challenge_slug>/<container>@sha256:<digest>
ghcr.io/msg-ctf/challenges/<challenge_slug>/<container>@sha256:<digest>
```

commit tag는 추적과 발행을 위한 입력이고 Runtime 계약은 digest입니다. `latest`는 만들지 않습니다.
Expand All @@ -83,30 +86,34 @@ commit tag는 추적과 발행을 위한 입력이고 Runtime 계약은 digest
KOTH 문제도 같은 규칙을 사용합니다. `info.yaml`의 `deployment.containers`에
선언된 `service`를 발행하며 로컬 Compose 전용 `checker`는 발행 대상이 아닙니다.

### 5. Atomic Publish 자료
### 5. Publish Bundle 자료

`scripts/generate_publish_bundle.py`가 두 파일을 생성합니다.

- `artifact-v2.json`: Runtime과 Scheduler가 읽을 immutable workload
- `registry-publish.json`: Challenge Registry가 한 transaction으로 revision을 추가하고 active를 전환할 요청
- `artifact-v2.json`: Backend poller 자동 수집과 Runtime이 읽을 immutable workload
- `registry-publish.json`: 같은 artifact를 감싼 수동 API 검증용 wrapper

Registry는 기존 active revision을 먼저 해제한 뒤 새 row를 쓰는 방식으로 처리하면 안 됩니다. 새 revision 저장과 active 전환이 하나의 transaction에서 성공해야 합니다. 실패하면 기존 active revision을 유지해야 합니다.
두 파일은 같은 `registry_revision`, `isolation_profile`과
`workload.containers[]`를 보존합니다. `workload.internal_connections[]`가 있으면
Runtime은 선언된 방향과 포트만 허용하는 NetworkPolicy를 생성합니다. CI는 raw
NetworkPolicy를 생성하거나 전달하지 않습니다.

실행 중 instance가 참조하는 revision은 active가 아니더라도 보존합니다.

Backend가 등록 API를 제공하면 reusable workflow의 `publish_registry`를 켜서
`registry-publish.json`을 HTTPS로 전달합니다. API는 `Idempotency-Key`를 기준으로
같은 문제와 revision의 중복 요청을 안전하게 처리해야 합니다. Registry 등록이
실패하면 새 revision을 배포 가능 상태로 간주하지 않습니다.
성공한 `-publish-bundle` Actions artifact의 `artifact-v2.json`이 자동 수집의
공식 입력입니다. Backend poller가 challenge 매핑, release 등록과 같은
`registry_revision`의 중복 처리를 소유하며, Backend/admin이 active release 전환과
롤백을 소유합니다. DevSecOps workflow에는 Backend base URL 또는 service token이
필요하지 않습니다.

## 팀 계약

### Challenge Registry

- DevSecOps: 검증된 revision publish
- DevSecOps: `artifact-v2.json`과 GHCR digest image 발행
- Backend poller: Actions artifact 수집, challenge 매핑, release 등록, duplicate 처리
- Scheduler: active revision read-only 조회
- Backend/Registry: slug와 `challenge_id` 매핑 및 transaction 제공
- DevSecOps와 Backend: `registry-publish.json` 요청 및 인증 계약 유지
- Backend/admin: active release 전환과 롤백

### Resource Broker

Expand All @@ -122,7 +129,12 @@ DevSecOps가 검증한 다음 필드를 그대로 사용합니다.

### Runtime 및 격리보안

DevSecOps는 `workload.containers[]`, `ports[].public`, `healthcheck`, `resource_profile`을 전달합니다. Runtime은 이를 이용해 Namespace, Pod, Service, Gateway, NetworkPolicy, SecurityContext와 cleanup을 구현합니다.
DevSecOps는 `isolation_profile`, `workload.containers[]`, `ports[].public`,
`workload.internal_connections[]`, `healthcheck`, `resource_profile`을 전달합니다.
Runtime은 이를 이용해 Namespace, Pod, Service, Gateway, NetworkPolicy,
SecurityContext와 cleanup을 구현합니다.
혼합 public/private port는 Runtime DTO가 확정될 때까지 손실 변환하지 않고
`artifact-v2.json`에 보존합니다.
발행 후 smoke test는 SSM으로 Runtime node 안의 Secure Provisioner API를 호출해
생성과 삭제 Operation이 모두 성공하는지만 확인합니다.

Expand Down
5 changes: 5 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,8 @@ Monitoring 팀과 맞춰야 할 계약도 포함합니다.

현재 GitHub 기준의 문제 저장소, Broker, Scheduler, Runtime, Monitoring 연동
상태와 미확정 항목도 기록합니다.

### `challenge-registry-integration.md`

Backend poller의 Actions artifact 수집 기반 release 등록 운영 계약과, 과거 로컬
Registry 등록의 호환성 증거를 기록합니다.
3 changes: 0 additions & 3 deletions docs/challenge-caller-example.yml
Original file line number Diff line number Diff line change
Expand Up @@ -118,13 +118,10 @@ jobs:
revision: ${{ github.run_number }}
devsecops_ref: 64a8d9267b2e7ea6a3eea5c92070d09ab1d76d8d
publish_images: true
publish_registry: ${{ vars.ENABLE_CHALLENGE_REGISTRY == 'true' }}
enable_k3s_smoke_deploy: ${{ vars.ENABLE_RUNTIME_SMOKE == 'true' }}
runtime_target_id: ${{ vars.RUNTIME_TARGET_ID }}
secrets:
AWS_ROLE_TO_ASSUME: ${{ secrets.AWS_ROLE_TO_ASSUME }}
AWS_REGION: ${{ secrets.AWS_REGION }}
AWS_K3S_INSTANCE_ID: ${{ secrets.AWS_K3S_INSTANCE_ID }}
AWS_CD_ARTIFACT_BUCKET: ${{ secrets.AWS_CD_ARTIFACT_BUCKET }}
CHALLENGE_REGISTRY_TOKEN: ${{ secrets.CHALLENGE_REGISTRY_TOKEN }}
CHALLENGE_REGISTRY_URL: ${{ secrets.CHALLENGE_REGISTRY_URL }}
Loading
Loading