chore: add best-practice repo structure and CI

.github/workflows/ci.yml

@@ -0,0 +1,73 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install ruff
+      - run: ruff check skills/ --config pyproject.toml
+      - run: ruff format --check skills/
+
+  test-iam-departures:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install boto3 moto pytest
+      - run: cd skills/iam-departures-remediation && pytest tests/ -v
+
+  validate-cloudformation:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install cfn-lint
+      - run: cfn-lint skills/iam-departures-remediation/infra/cloudformation.yaml
+      - run: cfn-lint skills/iam-departures-remediation/infra/cross_account_stackset.yaml
+
+  validate-terraform:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: "1.12.0"
+      - run: cd skills/iam-departures-remediation/infra/terraform && terraform init -backend=false && terraform validate
+
+  security-scan:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install bandit
+      - run: bandit -r skills/ -c pyproject.toml --severity-level medium || true
+      - name: Check for hardcoded secrets
+        run: |
+          # Fail if any obvious secret patterns found in Python source
+          ! grep -rn "AKIA[A-Z0-9]\{16\}" skills/ --include="*.py" || exit 1
+          ! grep -rn "sk-[a-zA-Z0-9]\{20,\}" skills/ --include="*.py" || exit 1
+          ! grep -rn "ghp_[a-zA-Z0-9]\{36\}" skills/ --include="*.py" || exit 1
+          echo "No hardcoded secrets found"

.gitignore

@@ -1 +1,52 @@
+# Python
 __pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Terraform
+.terraform/
+*.tfstate
+*.tfstate.backup
+*.tfplan
+.terraform.lock.hcl
+
+# Secrets (never commit)
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+terraform.tfvars
+
+# Build artifacts
+*.zip
+*.tar.gz

CLAUDE.md

@@ -0,0 +1,58 @@
+# Cloud Security Skills Collection
+
+This repository contains production-ready cloud security automations structured as skills for AI agents.
+
+## Repository structure
+
+```
+skills/
+  iam-departures-remediation/   — Multi-cloud IAM cleanup for departed employees
+  cspm-aws-cis-benchmark/       — CIS AWS Foundations v3.0 (18 checks)
+  cspm-gcp-cis-benchmark/       — CIS GCP Foundations v3.0 (20 checks + 5 Vertex AI)
+  cspm-azure-cis-benchmark/     — CIS Azure Foundations v2.1 (19 checks + 5 AI Foundry)
+  vuln-remediation-pipeline/    — Auto-remediate supply chain vulnerabilities
+```
+
+## Conventions
+
+- Each skill has a `SKILL.md` with frontmatter (name, description, license, compatibility, metadata, frameworks).
+- Source code lives in `src/` within each skill directory.
+- Infrastructure-as-code lives in `infra/` (CloudFormation, Terraform, StackSets).
+- Tests live in `tests/` within each skill directory.
+- All skills are Apache 2.0 licensed.
+- Python 3.11+ required. Type hints used throughout.
+- No hardcoded credentials. All secrets via environment variables or AWS Secrets Manager.
+
+## Security model
+
+- CSPM skills are read-only (no write permissions to cloud accounts).
+- Remediation skills use least-privilege IAM with cross-account STS AssumeRole.
+- Deny policies protect root, break-glass, and emergency accounts from deletion.
+- All S3 artifacts are KMS-encrypted. DynamoDB tables use encryption at rest.
+
+## Compliance frameworks referenced
+
+MITRE ATT&CK, NIST CSF 2.0, CIS Controls v8, CIS AWS/GCP/Azure Foundations, SOC 2 TSC, ISO 27001:2022, PCI DSS 4.0, OWASP LLM Top 10, OWASP MCP Top 10.
+
+## Running checks
+
+```bash
+# AWS CIS benchmark
+pip install boto3
+python skills/cspm-aws-cis-benchmark/src/checks.py --region us-east-1
+
+# GCP CIS benchmark
+pip install google-cloud-iam google-cloud-storage google-cloud-compute
+python skills/cspm-gcp-cis-benchmark/src/checks.py --project my-project
+
+# Azure CIS benchmark
+pip install azure-identity azure-mgmt-authorization azure-mgmt-storage azure-mgmt-monitor azure-mgmt-network
+python skills/cspm-azure-cis-benchmark/src/checks.py --subscription-id SUB_ID
+
+# IAM departures tests
+cd skills/iam-departures-remediation && pip install boto3 moto pytest && pytest tests/ -v
+```
+
+## Integration with agent-bom
+
+This repo provides the security automations. [agent-bom](https://github.com/msaad00/agent-bom) provides continuous scanning and compliance validation. Use together for detection + response.

CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+Contributions are welcome. This repo follows a skills-based structure — each security automation is a self-contained skill under `skills/`.
+
+## Adding a new skill
+
+1. Create a directory under `skills/` with a descriptive name (e.g., `skills/cspm-snowflake-cis-benchmark/`)
+2. Add a `SKILL.md` with the required frontmatter:
+
+```yaml
+---
+name: your-skill-name
+description: >-
+  One-paragraph description of what this skill does and when to use it.
+license: Apache-2.0
+compatibility: >-
+  Runtime requirements (Python version, cloud SDKs, permissions needed).
+metadata:
+  author: your-github-handle
+  version: 0.1.0
+  frameworks:
+    - Framework names this skill maps to
+  cloud: aws | gcp | azure | multi
+---
+```
+
+3. Put source code in `src/` within your skill directory
+4. Put infrastructure-as-code in `infra/` (CloudFormation, Terraform)
+5. Put tests in `tests/` — every skill should have tests
+6. Add your skill to the table in `README.md`
+
+## Code standards
+
+- Python 3.11+ with type hints
+- No hardcoded credentials — use environment variables or AWS Secrets Manager
+- Least-privilege IAM — document every permission your skill needs
+- Tests use `pytest` with `moto` for AWS mocking
+- Map to compliance frameworks where applicable (CIS, MITRE, NIST, OWASP)
+
+## Pull request process
+
+1. Fork the repo and create a feature branch
+2. Add or modify skills following the structure above
+3. Ensure tests pass: `pytest skills/your-skill/tests/ -v`
+4. Ensure linting passes: `ruff check .`
+5. Open a PR against `main` with a clear description
+
+## Security
+
+If you find a security vulnerability, do NOT open a public issue. See [SECURITY.md](SECURITY.md) for responsible disclosure instructions.