Runbook: Local Environment Setup

Audience: Jr. Admins, Sysadmins, future ISSO Last Updated: 03/09/2026 Owner: Max S., Director of ITOps

What This Runbook Does

Walks you through setting up your local machine so you can run, test, and develop scripts in the secops-pipeline project. By the end, you'll have:

The project repository cloned
Your local .env file configured with your credentials
PowerShell, Python, and Node.js ready to go
A successful test run against the test account

Prerequisites

Before you start, make sure you have:

A Pacific Debt company laptop enrolled in Intune
Your standard E3 user account (you do NOT need admin/elevated roles)
Access to Bitwarden (ask your team lead if you don't have it)
Git installed (winget install Git.Git if not)

Step 1: Clone the Repository

Open a terminal (PowerShell or Git Bash) and run:

git clone <repo-url> C:\Users\<your-username>\secops-pipeline
cd C:\Users\<your-username>\secops-pipeline

Replace with the actual repository URL. Ask your team lead if you don't have it.

Step 2: Set Up Your .env File

This is the most important step. The .env file holds your connection info so scripts know how to talk to Azure, Zendesk, and other services.

2a. Copy the example file

cp .env.example .env

2b. Fill in your values

Open .env in your editor (VS Code, Notepad++, etc.) and replace every placeholder with real values.

Where to find your values:

Variable	Where to Get It
`AZURE_TENANT_ID`	Bitwarden > IT Shared > Azure Tenant
`AZURE_CLIENT_ID`	Bitwarden > IT Shared > SecOps App Registration
`AZURE_CLIENT_SECRET`	Bitwarden > IT Shared > SecOps App Registration
`TEST_USER_UPN`	Pre-filled — should be `pdrveriato@pacificdebt.com`
`TEST_DEVICE_NAME`	Pre-filled — should be `PDR-TEST-LAPTOP`
`ZENDESK_API_TOKEN`	Bitwarden > IT Shared > Zendesk API
`ZENDESK_AGENT_EMAIL`	Your Pacific Debt email address
`SCREENCONNECT_*`	Bitwarden > IT Shared > ScreenConnect
`VERIATO_*`	Bitwarden > IT Shared > Veriato
`OPERATOR_NAME`	Your name (e.g., `Jane D`)
`OPERATOR_EMAIL`	Your Pacific Debt email

If a folder or entry doesn't exist in Bitwarden yet, stop and ask your team lead. Do not guess or use someone else's credentials.

2c. Verify it's gitignored

Run this to confirm your .env won't accidentally get committed:

git status

Your .env file should NOT appear in the output. If it does, something is wrong with .gitignore — stop and ask for help.

Step 3: Install PowerShell Modules

Open PowerShell as your normal user (not as Admin unless a script specifically requires it) and run:

# Microsoft Graph SDK (used for all Azure AD / Entra ID calls)
Install-Module Microsoft.Graph -Scope CurrentUser -Force

# Azure modules (for Key Vault and resource management)
Install-Module Az.Accounts -Scope CurrentUser -Force
Install-Module Az.KeyVault -Scope CurrentUser -Force

# Verify installation
Get-Module -ListAvailable Microsoft.Graph, Az.Accounts, Az.KeyVault

You should see all three modules listed with version numbers.

Step 4: Install Python

# Check if Python is installed
python --version

# If not installed:
winget install Python.Python.3.12

Then install project dependencies (once a requirements.txt exists):

pip install -r requirements.txt

Step 5: Install Node.js (for webhook/integration scripts)

# Check if Node is installed
node --version

# If not installed:
winget install OpenJS.NodeJS.LTS

Step 6: Verify Your Setup

Test Graph API connectivity (read-only)

# Connect with your standard user account
Connect-MgGraph -Scopes "User.Read"

# Verify you can read the test account
Get-MgUser -UserId $env:TEST_USER_UPN | Select-Object DisplayName, UserPrincipalName

# Disconnect when done
Disconnect-MgGraph

Expected result: You should see the display name and UPN for the pdrveriato test account.

Test Python environment

python -c "import os; print('Tenant:', os.getenv('AZURE_TENANT_ID', 'NOT SET'))"

Expected result: Should print your tenant ID (not "NOT SET").

Step 7: Understand the Rules

Before you write or run any script, read these files:

CLAUDE.md — Project rules, safety requirements, and coding standards. This is mandatory reading.
runbooks/README.md — Why we use .env files and where we're headed with secrets management.
lessons.md — What the team has learned so far (once it exists).

Key rules to remember:

Always test against pdrveriato first — never point scripts at real users during development
Always use -WhatIf or --dry-run before running anything that makes changes
Never hardcode credentials — always read from environment variables
If you're unsure, ask — it's better to ask a "dumb" question than to break production

Troubleshooting

Problem	Solution
`.env` values showing as "NOT SET"	Make sure you saved the file. Restart your terminal — env vars load on shell startup.
`Connect-MgGraph` fails	Check your `AZURE_TENANT_ID` is correct. Make sure your account has basic Graph read permissions.
`Install-Module` permission errors	Make sure you're using `-Scope CurrentUser`, not trying to install system-wide.
`git status` shows `.env`	Check that `.gitignore` exists and contains `.env`. Run `git rm --cached .env` if it was already tracked.
Python can't find modules	Make sure you ran `pip install` in the right directory. Check `python --version` matches expectations.

If you're stuck after 15 minutes, escalate to your team lead. Don't troubleshoot in circles.

Rollback

This runbook only sets up local tooling. If something goes wrong:

Delete the secops-pipeline folder
Re-clone from the repository
Start this runbook from Step 1

No production systems are affected by local environment setup.

Source: secops-pipeline/runbooks/environment-setup.md | Last synced: 2026-03-23T08:24:28Z | Do not edit in Zendesk -- changes will be overwritten on next sync.