apt-defense-lab

APT-style DevSecOps security lab on GCP that demonstrates offensive paths and defensive controls in one reproducible environment.

Disclaimer (read first)

Educational and authorized lab use only. This repo includes deliberately weak or vulnerable configurations (for example vulnerable-pool, demo node images, and proof-of-concept exploits under exploits/) to teach GKE security, WIF, Falco, Trivy, and detection pipelines. Use only in a disposable GCP project you control, with no production data and no traffic to third-party systems. Do not run scenarios against infrastructure you do not own or lack explicit written permission to test. You alone are responsible for legal compliance and organizational policy.

Connect:

Table of contents

• Disclaimer (read first)
• Infographic: pipeline at a glance
• What This Project Is For
• Architecture at a Glance
• Case study: parse_trivy_bq.py
• How to Install and Use (3 commands)
• Repository Layout
• Prerequisites
• Quick Start
• Pipelines and Evidence Flow
• Security Scenarios Included
• CI Identity Model
• Troubleshooting
• Suggested GitHub Topics (Project Tags)
• Documentation Index
• References
• Contributing

This repository is built for technical assessment and training:

• Kubernetes security scenarios (container escape, control-plane stress, CI/WIF abuse simulation)
• Defensive stack (Falco, NetworkPolicy, hardened WIF conditions, Shielded nodes)
• Detection and analytics pipeline (Cloud Logging -> BigQuery -> parser -> clean vulnerability table)

Infographic: GKE → Trivy → Log Router → BigQuery

One-page flow for recruiters / README preview (same path is detailed below and in docs/).

flowchart LR
  GKE[GKE workloads]
  TV[Trivy Operator]
  LR[Log Router]
  SK[Logging sink]
  BQ[(BigQuery)]
  PY[parse_trivy_bq.py]
  GKE --> TV --> LR --> SK --> BQ --> PY

Loading

What This Project Is For

apt-defense-lab is an isolated, non-production lab for:

• demonstrating realistic attacker behavior in cloud-native environments
• validating detection and prevention controls
• proving traceability from runtime signals to structured evidence
• comparing intentionally vulnerable vs hardened CI identity flows

Do not run exploit scenarios outside disposable lab projects you own.

Architecture at a Glance

GitHub Actions (PR / push / dispatch)
    |  OIDC -> Workload Identity Federation (lab/prod pools)
    v
GCP service accounts (cicd-lab / cicd-plan / cicd-apply)
    v
GKE Standard (lab-cluster)
  - vulnerable-pool   (demo attack surface)
  - hardened-pool     (shielded/hardened baseline)
  - trivy-operator    (scan results in logs)
  - falco             (runtime detection)
  - network policies  (egress control)

Cloud Logging sink -> BigQuery dataset (trivy_logs)
    v
scripts/parse_trivy_bq.py -> clean_vulnerabilities

Architecture (Mermaid)

flowchart TB
  subgraph CI["GitHub Actions"]
    A[Workflows: vulnerable / hardened / apply]
  end
  subgraph GCP["GCP"]
    WIF[Workload Identity Federation]
    SA[Service accounts: cicd-lab / plan / apply]
    GKE[GKE lab-cluster]
    subgraph Pools["Node pools"]
      V[vulnerable-pool]
      H[hardened-pool]
    end
    T[Trivy operator]
    F[Falco]
    NP[NetworkPolicy]
    LOG[Cloud Logging]
    BQ[(BigQuery: trivy_logs)]
    P[parse_trivy_bq.py → clean_vulnerabilities]
  end
  CI --> WIF
  WIF --> SA
  SA --> GKE
  GKE --> Pools
  GKE --> T
  GKE --> F
  GKE --> NP
  T --> LOG
  LOG --> BQ
  BQ --> P

Loading

Data path: Trivy → BigQuery → normalized table (Mermaid)

flowchart LR
  TR[Trivy Operator]
  LG[Workload logs]
  LR[Log Router]
  SK[Logging sink]
  BQ[(Dataset: trivy_logs)]
  PY[scripts/parse_trivy_bq.py]
  CV[Table: clean_vulnerabilities]
  TR --> LG --> LR --> SK --> BQ --> PY --> CV

Loading

Extended narrative (sink fields, compression, queries): docs/logging_pipeline.md and docs/network-and-data-flow.md.

Case study: parse_trivy_bq.py

Problem	Raw scan telemetry in Cloud Logging / BigQuery is noisy and inconsistent — hard to trend CVEs, build executive summaries, or join with asset inventory.
What we built	A managed sink into trivy_logs plus scripts/parse_trivy_bq.py to read sink exports, normalize records, and populate a clean table for analytics (clean_vulnerabilities / pipeline in repo).
Outcome	Security-as-code evidence: repeatable ETL, simpler SQL for audits, and a pattern you can reuse for other log sources (Falco, custom scanners).

How to Install and Use (3 commands)

From repo root, after installing gcloud, terraform, kubectl (see Prerequisites below):

git clone https://github.com/kiurakku/APT-SecureOps-Lab.git
cd APT-SecureOps-Lab/terraform && cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars (project_id, github_org, github_repo, state bucket), then:
terraform init -backend-config=backend.hcl && terraform apply

Full kubectl, Helm, and GitHub secrets steps are in Quick Start below — the three commands above bootstrap infra; follow sections 3–4 there for cluster access and CI wiring.

Repository Layout

Path	Purpose
terraform/	GCP infrastructure (GKE, IAM, WIF, BigQuery, logging sink)
.github/workflows/	Vulnerable plan, hardened plan, controlled apply workflows
k8s/	Helm values and Kubernetes manifests (Trivy, Falco, policies)
cloudbuild/	Build/deploy/parser Cloud Build configs
scripts/	Utility scripts (parser, sink inspection, policy apply, checks)
exploits/	Controlled PoC scenarios for assignment-only lab use
docs/	Runbooks, architecture notes, and implementation guidance

Prerequisites

• GCP project with billing enabled
• gcloud, terraform >= 1.5, kubectl, helm
• Python 3.11+
• GitHub repository with Actions enabled

Windows note (gcloud not found):

• install Google Cloud SDK
• ensure Cloud SDK bin is in PATH
• reopen shell and verify with gcloud --version

Quick Start

1) Configure Terraform variables

cd terraform
cp terraform.tfvars.example terraform.tfvars

Set values in terraform.tfvars:

• project_id
• github_org
• github_repo
• tf_state_bucket_name

2) Initialize backend and apply

PowerShell:

terraform init "-backend-config=backend.hcl"
terraform apply

Bash:

terraform init -backend-config=backend.hcl
terraform apply

If you cannot use remote state yet:

terraform init -backend=false
terraform apply

3) Connect kubectl

gcloud container clusters get-credentials lab-cluster --zone YOUR_ZONE --project YOUR_PROJECT

4) Configure GitHub secrets

Use Terraform outputs:

• WIF_PROVIDER_LAB
• WIF_PROVIDER_PROD
• CICD_LAB_SA_EMAIL
• CICD_PLAN_SA_EMAIL
• CICD_APPLY_SA_EMAIL
• DEMO_IMPACT_BUCKET

Also set:

• GCP_PROJECT_ID
• TF_STATE_BUCKET

5) Deploy security stack

Use pinned chart versions from file headers and deploy:

• Trivy Operator
• Falco
• network policies

Then enable compressed Trivy logs:

bash scripts/configure_trivy_log_compression.sh

Pipelines and Evidence Flow

Cloud Build

Config	Outcome
cloudbuild/cloudbuild.yaml	Build/push lab-ci/ci-deploy image
cloudbuild/deploy-gke-apps.yaml	Deploy Trivy + Falco + NetworkPolicy
cloudbuild/run-trivy-parser.yaml	Parse sink rows into clean_vulnerabilities

BigQuery evidence

Terraform creates a managed Logging sink to trivy_logs.
Inspect sink tables:

python scripts/bq_sink_inspect.py --project YOUR_PROJECT --dataset trivy_logs

Parse sink data:

cd scripts
python parse_trivy_bq.py --project YOUR_PROJECT --dataset trivy_logs --from-sink

Security Scenarios Included

• exploits/container_escape/: CVE-2022-0492 class mechanics (cgroup-dependent behavior)
• exploits/master_plane_crash/: API load stress via mass object creation
• exploits/github_action_steal/: WIF misuse simulation in CI context

All exploit paths are educational and must run only in isolated lab environments.

CI Identity Model

• vulnerable-tf-plan.yml: PR-triggered broad lab WIF path -> cicd-lab-sa
• hardened-tf-plan.yml: push-to-main strict WIF conditions -> cicd-plan-sa
• hardened-tf-apply.yml: manual controlled write only -> demo-write-proof.txt

This split is intentional to demonstrate blast radius differences.

Troubleshooting

• gcloud not recognized (Windows): fix PATH and restart shell
• get-credentials 404/403: verify exact --zone/--region, IAM permissions, active project
• No sink evidence rows: wait for new scan job logs, inspect stderr_* and stdout_*
• No clean_vulnerabilities rows: run parser and verify table/schema access
• Falco shows only internal debug drops: trigger explicit test event (/tmp write) and capture alert lines

Suggested GitHub Topics (Project Tags)

Add these repository topics for discoverability:

• devsecops
• gke
• kubernetes-security
• terraform
• workload-identity-federation
• github-actions
• cloud-build
• falco
• trivy
• bigquery
• cloud-logging
• threat-detection
• security-lab
• red-team
• blue-team

Contributing

Pull requests are welcome. Read CONTRIBUTING.md before you submit — especially the Disclaimer and rules for exploits/.

Documentation Index

• docs/README.md - documentation index
• docs/github_actions_runbook.md - end-to-end GitHub/GCP flow
• docs/logging_pipeline.md - sink/parser data path
• docs/architecture_and_stack.md - architecture detail
• docs/network-and-data-flow.md - network / logging / BigQuery flow (Mermaid)

References

• GKE Security Bulletins
• GKE Workload Identity
• Trivy Operator Configuration
• CVE-2022-0492 (NVD)