Lab Environment Setup Guide

Overview

The Noctua lab environment is designed for graduate students to build real agentic cybersecurity tools using Claude's autonomous agent capabilities. Rather than relying on traditional infrastructure, this course centers on rapid prototyping with Claude Max subscription, supplemented by open-source frameworks for multi-vendor exposure.

You will develop autonomous security agents capable of threat detection, incident response, vulnerability assessment, and security architecture using Claude's Agent SDK, MCP servers, and agent teams.

Required Accounts

Claude Max Subscription (Required)

A Claude Max subscription is required for all course work. This provides access to:

• Claude Code CLI — command-line interface for autonomous code generation
• Claude Agent SDK — framework for building agentic workflows with tool use
• Worktrees — isolated development branches for parallel experimentation
• Subagents — specialized agents delegated to specific security domains
• MCP Servers — bidirectional communication between Claude and custom tools
• Agent Teams — orchestrated multi-agent systems for complex security operations

Claude Max is available through institutional purchase (check with your program) or individual subscription. Verify your subscription level grants access to all agent capabilities.

Additional Accounts (Free Tier Sufficient)

• GitHub (Required) — all course work is Git-based. SSH key authentication recommended. github.com
• OpenAI Platform (Unit 5 only) — free tier with initial credit sufficient for the OpenAI Agents SDK comparison week. platform.openai.com
• Ollama (Free, Local) — open-weight model labs and sensitive data scenarios. No account required.

Option A: Local Machine Setup (Primary)

This is the standard course setup. Claude Code runs in your local terminal alongside a browser window showing the lab guide. Most labs assume this two-screen pattern.

Step 1: Install Python 3.11+

macOS (Homebrew):

brew install python@3.11
python3 --version

Windows: Download from python.org/downloads and run the installer. Check "Add Python to PATH".

python --version

Linux:

sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip
python3 --version

Step 2: Install Node.js 20+

macOS:

brew install node@20
node --version && npm --version

Windows: Download the LTS installer from nodejs.org.

node --version && npm --version

Linux (NodeSource):

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs
node --version

Step 3: Install Git

• macOS: brew install git
• Windows: Download from git-scm.com
• Linux: sudo apt install git

Configure identity and generate SSH keys:

git --version
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Generate SSH key for GitHub authentication
ssh-keygen -t ed25519 -C "your.email@example.com"
cat ~/.ssh/id_ed25519.pub  # Copy output → GitHub Settings > SSH Keys

Step 4: Install Docker Desktop

Docker is required for Semester 2 containerized labs and simulated security environments.

• macOS / Windows: Download from docker.com/products/docker-desktop
• Linux: Follow docs.docker.com/engine/install

docker --version
docker run hello-world

Step 5: Install GitHub CLI

Used for managing repositories, pull requests, CI/CD workflows, and container registry operations.

• macOS: brew install gh
• Windows: winget install --id GitHub.cli
• Linux:

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli-stable.list > /dev/null
sudo apt update && sudo apt install gh

gh auth login
gh --version

Step 6: Install Claude Code CLI

The Claude Code CLI is the primary interface for autonomous development in this course.

npm install -g @anthropic-ai/claude-code
claude --version

Option B: GitHub Codespaces (Isolation Alternative)

Use Codespaces when you need a fully isolated cloud environment — for example, when working with sensitive lab data you don't want on your local machine, or when your local environment has conflicts you can't resolve quickly.

1. Fork the Noctua course repository to your GitHub account
2. Click the green "Code" button on your fork, select the "Codespaces" tab
3. Click "Create codespace on main" — environment initializes in 2–3 minutes
4. A browser-based VS Code session opens with Python, Node.js, Git, and GitHub CLI pre-installed
5. Install Claude Code CLI inside the Codespace:

npm install -g @anthropic-ai/claude-code
claude login

Claude Code CLI Setup

Authenticate

claude login

A browser window opens to authenticate with your Claude account. Complete the login flow and return to the terminal. Your authentication token is stored locally.

Verify and Configure

claude --version
claude config list

Claude Code is configured through a CLAUDE.md file in your project root. The course repository already includes one with course-specific instructions — you don't need to create it manually. MCP servers are registered with claude mcp add (covered in Unit 2 labs); each lab guide specifies which servers to register.

Run Your First Command

claude "Create a simple Python script that prints 'Noctua Lab Environment Ready'"

Claude generates the script, saves it, and reports success. This confirms your setup is working.

MCP Server Development Setup

Throughout the course you will build MCP (Model Context Protocol) servers to extend Claude's capabilities for security operations. MCP servers act as bridges between Claude and external tools, APIs, data sources, and custom security functions.

Install MCP SDKs

Python MCP SDK (primary for security tools):

pip install mcp

TypeScript MCP SDK (optional, if you prefer Node.js):

npm install @modelcontextprotocol/sdk

Verification: Hello World MCP Server

Create a file hello_mcp_server.py:

import asyncio
import json
from mcp.server.lowlevel import Server
from mcp.types import Tool, TextContent, ToolResult

server = Server("hello-mcp")

@server.tool()
async def get_security_status(tool_name: str) -> str:
    """Returns a mock security status report."""
    return json.dumps({
        "status": "secure",
        "threats": 0,
        "agent_version": "1.0"
    })

async def main():
    async with server:
        print("Hello World MCP Server running...")
        await asyncio.Future()  # Run forever

if __name__ == "__main__":
    asyncio.run(main())

python hello_mcp_server.py

If it starts without errors, your MCP development environment is ready.

Dependency Security: Before You pip install

For every project in this course:

1. Use virtual environments per project — blast radius containment
2. Pin dependencies by hash, not just version number
3. Run pip-audit before first use and in CI
4. Never commit secrets to Git — use environment variables or the Noctua Keystore

# Install tooling
pip install pip-tools pip-audit

# Generate hash-pinned requirements (do this once per project)
pip-compile --generate-hashes requirements.in -o requirements.txt

# Install with hash verification
pip install --require-hashes -r requirements.txt

# Audit for known CVEs
pip-audit

Agent Framework Setup (Semester 2, Unit 5)

Unit 5 compares three agent harnesses against the same security scanning workload. Install these before starting Unit 5. All three use the MASS 7-agent DAG from tools/mass/ in the course repo.

Claude SDK (Week 1 — already installed)

Custom agent loop using the Anthropic Python SDK. Installed in Week 4 of Semester 1.

pip install anthropic pyyaml httpx
python -c "import anthropic; print(anthropic.__version__)"

OpenAI Agents SDK (Week 2)

Runner-managed loop in your process. Agent + @function_tool + Runner.run_sync(). Requires an OpenAI Platform API key.

pip install openai-agents pydantic
python -c "from agents import Agent; print('OpenAI Agents SDK installed')"

Claude Managed Agents (Week 3)

Anthropic-hosted loop. Deploy agents once; run per-session scans. Requires only your existing Anthropic API key.

# No additional install — uses the anthropic package already installed
# Deploy the MASS agents:
cd tools/mass/claude-managed-agents
python deploy.py deploy

MASS 2.0 — Course Security Tool

The MASS 7-agent security scanner is included in the course repo at tools/mass/. Both implementations (Claude Managed Agents and OpenAI Agents SDK) are ready to run and extend.

# Verify MASS tools are present
ls tools/mass/claude-managed-agents/
ls tools/mass/openai-sdk-agents/

Ollama (Local Models)

Runs open-weight models locally — useful for offline security work and sensitive data labs.

Install Ollama:

• macOS / Windows: Download from ollama.ai (WSL 2 required on Windows)
• Linux:

curl -fsSL https://ollama.ai/install.sh | sh

Pull a model (~2 GB download):

ollama pull llama3.2
ollama list  # Verify model appears

Alternative models:

• ollama pull mistral — faster, lighter footprint
• ollama pull llama3.1:8b — strong reasoning, 8B parameters
• ollama pull phi4-mini — low-latency, small footprint

Course Repository Setup

Fork and Clone

1. Navigate to the Noctua course repository on GitHub
2. Click "Fork" (top right) and select your account as the fork destination
3. Clone your fork locally:

git clone git@github.com:YOUR-USERNAME/Noctua.git
cd Noctua

Add Upstream Remote

Allows you to sync with course updates:

git remote add upstream git@github.com:r33n3/Noctua.git
git fetch upstream

Branch Strategy

• main — official course releases (do not commit here)
• dev — your personal development branch for in-progress work
• lab-XX — individual branches per lab (e.g., lab-01, lab-02)

# Create your dev branch
git checkout -b dev
git push -u origin dev

# For each lab, create a new branch
git checkout -b lab-01
# ...work on lab...
git commit -am "Complete lab 01: threat detection agent"
git push -u origin lab-01

Syncing with Course Updates

git fetch upstream
git rebase upstream/main
git push origin main

DevSecOps Promotion Pipeline

Noctua follows a DevSecOps methodology for promoting prototypes from local development to production deployment. This isn't a DevSecOps course — but we follow the methodology so that when a prototype is selected for delivery, the path to production is already paved.

The Promotion Path

Local Development (Docker Desktop) — every prototype starts as a containerized application on Docker Desktop. From Week 1, containerize agents with a Dockerfile and docker-compose.yml. This ensures reproducibility, isolation, and a clean path to cloud deployment.

Version Control & CI (GitHub + gh CLI) — all code lives in GitHub. GitHub Actions handles automated testing, linting, and security scanning on every push.

Container Registry — when a prototype graduates from local Docker to cloud deployment, images are pushed to a container registry (GitHub Container Registry for this course). Tag and push your image, then deploy via your cloud provider's container service.

# Push to GitHub Container Registry
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
docker tag my-agent:latest ghcr.io/USERNAME/my-agent:latest
docker push ghcr.io/USERNAME/my-agent:latest

Infrastructure as Code — production infrastructure is defined in code (Terraform or Pulumi), not clicked in consoles. This ensures repeatability, auditability, and version-controlled infrastructure changes. Unit 7 covers deploying your agent to a cloud provider of your choice.

Security Gates

• Pre-commit — secrets detection (no API keys in code), linting, type checking
• PR Review — automated security scanning, peer code review, Claude Code review
• Build — container image scanning for vulnerabilities (Trivy, Snyk)
• Registry — image signing and provenance verification
• Deploy — environment-based promotion gates (dev → staging → prod), runtime policy enforcement
• Production — observability, anomaly detection, audit logging

Containerization from Day 1

Every lab prototype should include a minimal Dockerfile:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "agent.py"]

And a docker-compose.yml for local development:

version: "3.8"
services:
  agent:
    build: .
    ports:
      - "8080:8080"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./data:/app/data

Course Security Research Platforms

MASS (Model & Application Security Suite)

MASS is a production-grade 7-agent AI security scanner included in this course repo at tools/mass/. It scans AI agent systems for vulnerabilities: prompt injection, jailbreaks, secrets, MCP misconfigs, agentic topology risks, and compliance gaps. It produces structured findings, a tribunal verdict, and deployable security policies (Cedar, Claude API guardrails, LiteLLM, nginx, NeMo).

Two implementations — same DAG, different harness:

• tools/mass/claude-managed-agents/ — Anthropic-hosted loop. Deploy once with deploy.py; run scans as sessions.
• tools/mass/openai-sdk-agents/ — Runner-managed loop in your process. python 01-orchestrator.py /path/to/scan/target

What MASS demonstrates (source code to study):

• Orchestrator DAG pattern — Phase 1–9 pipeline with parallel workers, conditional red team, parallel tribunal
• Tribunal aggregation — 3 judges with weighted scoring (security 0.40, remediation 0.30, evidence 0.30)
• Policy generation — Cedar, Claude API guardrails, LiteLLM config, nginx config, NeMo Guardrails colang
• OWASP LLM Top 10, MITRE ATLAS, NIST AI RMF, AIUC-1 compliance mapping

PeaRL (Policy-enforced Autonomous Risk Layer)

PeaRL is an AI security tool demonstrating governance and oversight challenges in production autonomous agent deployments. You will study how PeaRL approaches environment-based promotion gates, policy-as-code enforcement, behavioral anomaly detection, and approval workflows.

What PeaRL Teaches (Source Code to Study):

Study the PeaRL repository at github.com/r33n3/PeaRL to understand:

• Environment Hierarchy — design pattern for agent environment progression (dev → staging/pilot → pre-production → production)
• Approval Workflow Pattern — multi-stage approval systems with stakeholder roles and delegation
• Fairness Requirements Framework — systematic evaluation of agent behavior for bias
• Behavioral Anomaly Detection — pattern analysis for detecting unexpected or dangerous agent behavior

Anomaly Governance Patterns (AGP-01 through AGP-05):

• AGP-01 — Excessive tool usage pattern
• AGP-02 — Out-of-scope action pattern
• AGP-03 — Fairness violation pattern
• AGP-04 — Data leakage pattern
• AGP-05 — Behavior drift pattern

AI Security Tools

Red Teaming & Adversarial Testing

# Garak (NVIDIA) — LLM vulnerability scanner
pip install garak
garak --list_probes  # List available probe modules

# PyRIT (Microsoft) — Multi-turn adversarial red teaming
pip install pyrit
# Requires Azure OpenAI or compatible endpoint configuration

# Promptfoo — Red teaming with compliance mapping
npm install -g promptfoo
promptfoo init         # Initialize config
promptfoo redteam run  # Run red team evaluation

# DeepTeam — LLM vulnerability testing (40+ vulnerability types)
pip install deepteam

Guardrails & Governance

# NeMo Guardrails (NVIDIA) — Programmable LLM guardrails
pip install nemoguardrails
nemoguardrails chat --config ./config/

# Guardrails AI — Runtime validation framework
pip install guardrails-ai
guardrails hub install hub://guardrails/toxic_language

# Cisco MCP Scanner — MCP supply chain security
pip install mcp-scanner
mcp-scanner scan  # Scans MCP configurations for vulnerabilities

LlamaFirewall (Meta) — Agent Security

pip install llamafirewall
# Three defense layers: PromptGuard 2, Agent Alignment Checks, CodeShield
# See: https://github.com/meta-llama/llama-firewall

Fairness & Bias Assessment

# IBM AI Fairness 360
pip install aif360

# Aequitas (University of Chicago)
pip install aequitas

Traditional Security Tools (Supplementary)

Certain labs may use traditional tools for data collection and manual verification:

• Wireshark: brew install wireshark (macOS) or sudo apt install wireshark (Linux)
• nmap: brew install nmap or sudo apt install nmap
• Burp Suite Community: portswigger.net/burp/communitydownload

Mock Data and Simulated Environments

The course provides Docker Compose files for creating realistic lab environments without exposing real systems. Available environments (in /lab-environments/):

• mock-siem — simulated SIEM with sample security events and logs
• vulnerable-app — intentionally vulnerable web application for security testing
• network-traffic — captured network traffic samples for analysis
• log-repository — large dataset of real sanitized security logs

cd lab-environments/mock-siem
docker-compose up -d

# Access SIEM dashboard
open http://localhost:5601

# Stop when done
docker-compose down

Verification Checklist

Complete every item before beginning Week 1 coursework. Run the provided command for each item — if any fail, consult the Troubleshooting section or post in the course forum.

Core Development Tools

• Claude Max subscription active and verified
• Claude Code CLI installed (claude --version)
• Claude Code CLI authenticated (claude login)
• Python 3.11+ installed (python3 --version)
• pip working (pip --version)
• Node.js 20+ installed (node --version)
• npm working (npm --version)
• Git installed and configured (git config --list)
• SSH keys generated and added to GitHub
• GitHub account created and accessible
• Course repository forked and cloned locally
• Git branches (main, dev) verified
• Docker Desktop installed and running (docker --version)
• GitHub CLI installed and authenticated (gh auth status)
• AWS CLI v2 installed — Semester 2 only (aws sts get-caller-identity)

Agentic Frameworks and MCP

• MCP SDK installed (pip list | grep mcp)
• Hello World MCP server runs successfully (hello_mcp_server.py)
• CrewAI installed — Semester 2 only
• LangGraph installed — Semester 2 only
• AG2 (AutoGen) installed — Semester 2 only
• Ollama installed with at least one model (ollama list)
• OpenAI API account created — Semester 2 only

Course Security Platforms (Architecture Review)

• Reviewed MASS source code architecture (12 analyzers, compliance mapping patterns)
• Reviewed MASS MCP server design pattern for tool exposure
• Reviewed PeaRL source code architecture (environment hierarchy, approval workflows, fairness patterns)
• Understood PeaRL governance model and anomaly detection patterns (AGP-01 through AGP-05)

Troubleshooting

Claude Code CLI Issues

Python and Dependency Issues

pip install --upgrade mcp
python3 -m pip install mcp  # Use python3 explicitly if python points to Python 2

python3 -m venv noctua-env
source noctua-env/bin/activate  # macOS/Linux
# OR
noctua-env\Scripts\activate     # Windows
pip install -r requirements.txt

Docker Issues

sudo usermod -aG docker $USER
newgrp docker
docker ps  # Test

Git and GitHub Issues

cd Noctua
git status

Node.js and npm Issues

npm list -g          # See installed packages
which npm            # Verify npm location
npm config get prefix  # Check global install directory

Ollama Issues

ollama list           # Verify model is listed
ollama show llama3.2  # Get model details
ollama rm llama3.2    # Remove and repull if corrupted
ollama pull llama3.2

Cost Considerations

Claude Max Subscription

• Current pricing: $20/month (subject to change — verify in your account)
• Institutional pricing may be available through your program
• Includes all Claude Code, Agent SDK, and MCP capabilities

OpenAI API (Semester 2)

• Pricing varies by model — check current rates at platform.openai.com/pricing
• New accounts receive initial credit — verify amount when you sign up
• Typical course usage: $10–20 per student for Semester 2
• Use local models (Ollama) for cost-sensitive labs

GitHub Codespaces (Option B only)

• Free tier: 60 core-hours per month — sufficient for occasional isolation labs
• Paid: usage billed per core-hour beyond free tier
• Not recommended as primary environment — use local setup for daily course work

All Other Tools

Python, Node.js, Git, Docker Desktop, MCP SDK, CrewAI, LangGraph, AutoGen, Ollama, Wireshark, nmap — all free and open-source. Burp Suite Community is free; Pro is $399/year.

Estimated Cost Per Student (Full Year)

• Minimum: $240 (Claude Max, $20/month × 12)
• Typical: ~$255 (Claude Max + OpenAI API usage)
• Maximum: ~$650 (if using Burp Suite Pro)

Most students will fall in the typical range. Financial hardship policies should be coordinated with your program.

Next Steps

1. Complete the Verification Checklist above
2. Post any blockers to the course discussion forum with the specific error message
3. Clone the course repository and review the /labs directory structure
4. Open docs/lab-s1-unit1.html — that's your guide for Week 1
5. Join the course Slack/Discord for real-time support and peer collaboration