# Documentation and Evidence Path

## Preferred evidence order

1. Microsoft Learn documentation through the user's configured documentation MCP for documented Azure behavior.
2. Sampled read-only Azure evidence, when safely available, for current configured-environment observations.
3. Sanitized user-provided evidence.
4. Clearly labeled inference.

## What each evidence type can prove

- Microsoft Learn documentation can prove documented service behavior, supported concepts, limitations, and recommended patterns.
- Sampled read-only evidence can prove the sampled configured state at the time observed.
- Sanitized user evidence can prove only what the snippet shows.
- None of these alone prove broad regional availability, future success, full account posture, or production readiness.

## Safe usage pattern

- State whether each claim is documentation-based, sampled-current-state, user-provided, or inference.
- Use read-only queries before recommending changes.
- Do not include sensitive internal identifiers, tenant identifiers, subscription identifiers, or secrets in committed docs or final findings.
- If no sampled evidence is available, say the review is documentation-based and list the exact evidence still needed.

# Official Sources

Use these sources to ground the skill. Microsoft Learn documentation proves documented Azure behavior; it does not prove the user's tenant, subscription, RBAC, quota, migration project, network, telemetry, deployed resources, or production readiness.

## Primary Microsoft Learn sources

- https://learn.microsoft.com/entra/id-governance/privileged-identity-management/pim-configure
- https://learn.microsoft.com/entra/id-governance/privileged-identity-management/pim-resource-roles-activate-your-roles
- https://learn.microsoft.com/entra/id-governance/privileged-identity-management/pim-resource-roles-configure-role-settings
- https://learn.microsoft.com/entra/id-governance/privileged-identity-management/pim-resource-roles-approval-workflow
- https://learn.microsoft.com/entra/id-governance/privileged-identity-management/pim-deployment-plan
- https://learn.microsoft.com/entra/identity/role-based-access-control/best-practices

## Grounding notes

- Documentation-based claim: Microsoft Learn evidence says PIM provides just-in-time, time-bound, approval-based privileged access for Microsoft Entra and Azure resources. Azure resource role activation can require MFA, reduced scope, start time, duration, and reason; approval can leave a request pending. PIM temporarily adds active assignment and later removes it, but applications can cache role state so access changes may not appear immediately.
- Current-state claim: requires sampled read-only Azure evidence or sanitized user-provided evidence.
- Inference: allowed only when labeled and tied to observed fields or documented behavior.
- Do not include sensitive internal identifiers or secret material in findings.

## Source use rules

- Prefer Microsoft Learn documentation through the user's configured documentation MCP for current Azure service behavior.
- Use sampled read-only Azure evidence only to validate current configured-environment observations.
- If documentation and sampled evidence appear to conflict, report both and stop short of a production-ready verdict.
- Re-check official sources before changing high-risk guidance, because cloud behavior and feature availability can change.

# Permission Model: Azure Live PIM JIT Activation Guard

## Identity model

PIM JIT is itself the least-privilege mechanism. The operator holds only an *eligible assignment*
— not a standing active one. Activation is time-bounded, MFA-gated, and audit-logged natively.

Preferred model:
1. Entra ID PIM eligible assignment (never standing active)
2. Maximum activation duration: 1–4 hours for break-glass; 8 hours absolute maximum
3. Require approval for roles with management-group or subscription scope
4. Require justification and ticket reference for all activations

## Custom role — read eligible assignments and submit own activation

```json
{
  "Name": "PIM JIT Activation Operator",
  "IsCustom": true,
  "Description": "Read PIM eligible assignments and submit own activation requests.",
  "Actions": [
    "Microsoft.Authorization/roleEligibilitySchedules/read",
    "Microsoft.Authorization/roleEligibilityScheduleRequests/read",
    "Microsoft.Authorization/roleAssignmentSchedules/read",
    "Microsoft.Authorization/roleAssignmentScheduleRequests/write",
    "Microsoft.Authorization/roleAssignments/read"
  ],
  "NotActions": [],
  "AssignableScopes": [
    "$APPROVED_AZURE_SCOPE"
  ]
}
```

`roleAssignmentScheduleRequests/write` only allows a principal to activate their **own**
eligible assignment. It does not allow activating another user's role.

## Recommended PIM settings (configure in Entra portal or Graph API)

- Maximum activation duration: 8 hours
- Require MFA on activation: **Yes**
- Require justification: **Yes**
- Require ticket information: **Yes** (link to change management system)
- Require approval for: Owner, User Access Administrator, Global Administrator
- Notification on activation: send to security team distribution list

## Graceful degradation (tenants without P2 license)

Use Conditional Access + time-bounded Entra ID Group membership via Access Packages
(Entra ID Governance) as the nearest equivalent to PIM eligible assignment.

## Do not assign

- Standing `Owner` at subscription scope
- Standing `User Access Administrator` (allows arbitrary role assignments)
- `Microsoft.Authorization/roleAssignments/write` to non-PIM principals

Use exact resource scopes from approved change records; do not paste raw subscription identifiers into chat.

# Azure PIM JIT Activation Operations

Use this reference for current, source-grounded service behavior and the hard review gates that the lean `SKILL.md` intentionally does not carry.

## What people get wrong

- Treating eligible assignment as active access.
- Activating the broadest eligible scope instead of reducing scope to the actual resource needed.
- Skipping justification, ticket, MFA, or approval because the task is urgent.
- Assuming deactivation instantly removes access from every downstream application cache.
- Trying to activate another user’s eligible role from an agent context.

## Officially grounded service shape

Microsoft Learn evidence says PIM provides just-in-time, time-bound, approval-based privileged access for Microsoft Entra and Azure resources. Azure resource role activation can require MFA, reduced scope, start time, duration, and reason; approval can leave a request pending. PIM temporarily adds active assignment and later removes it, but applications can cache role state so access changes may not appear immediately.

- PIM role settings are configured per role and per resource.
- Eligible members activate roles only when needed and within configured maximum duration.
- Activation can require MFA, justification, ticket information, Conditional Access, and approval.
- Users can view pending requests, cancel pending requests, and deactivate active assignments subject to timing rules.
- PIM audit and notification signals are part of the control, not optional decoration.

## Non-negotiable design rules

- Confirm the eligible principal is the requester or authorized approver; do not impersonate activation.
- Require the narrowest scope, shortest duration, and explicit business reason.
- Require approval state before treating access as usable.
- Document cache and sign-out/sign-in caveats for access add/remove.
- Refuse activation when target scope, role, principal, approval, or rollback/deactivation path is ambiguous.

## Minimal safe implementation flow

- Scope principal, role, resource scope, duration, approval workflow, and task ticket.
- Collect read-only evidence of eligibility, current active assignments, PIM role settings, and request status.
- Check MFA, Conditional Access, approval, justification, and reduced-scope requirements.
- If mutation is requested, require explicit user approval before activation, approval, cancellation, or deactivation.
- Verify request status, active assignment, expiry time, audit evidence, and deactivation plan.

## High-risk assumptions to kill

- Eligible does not mean active. Do not treat an eligible assignment as usable access until request status proves activation or approval state.
- PIM activation is not a way for an agent to impersonate another human; the eligible principal or authorized approver boundary must remain explicit.
- Broad management-group or subscription activation is not justified when a narrower resource scope satisfies the task.
- Deactivation is not an instant proof of downstream access removal because applications can cache role state.
- Approval, MFA, justification, ticket, and duration controls are not paperwork; they are the evidence that privileged access was bounded.

## Safe command/code verification targets

- Verify eligible assignment, active assignment, request status, role settings, approval requirement, MFA requirement, and maximum duration before any activation path.
- Check reduced scope and shortest viable duration before submitting or approving an activation.
- Capture request state as pending, approved, active, denied, canceled, expired, or deactivated; do not infer it from intent.
- Verify audit evidence and expiry/deactivation plan after activation.
- State access-cache and sign-out/sign-in caveats whenever access add/remove is part of the verdict.

## Safe verification targets

- Eligible assignment exists for the requested principal and scope.
- Activation duration is within policy and no broader than operational need.
- MFA/approval/justification/ticket controls are satisfied where required.
- Audit or request status proves pending, active, denied, canceled, expired, or deactivated state.
- Access-cache caveat and sign-out/sign-in mitigation are stated.

## When to push back

- The user asks the agent to activate someone else’s role.
- Scope or role is broader than the task requires.
- Approval workflow is bypassed or approval owner is unclear.
- The user needs permanent access but calls it JIT.

# Preflight Commands: Azure Live PIM JIT Activation Guard

Run these before initiating or approving a PIM activation.

## Evidence-variable convention

Shell variables in examples are local operator placeholders from an approved change record or already configured shell context. Do not commit real values, and redact them from shared evidence unless disclosure is explicitly approved.

## 1. Confirm current principal identity

```bash
az account show --query "{subscription:id, name:name, user:user.name}"
az ad signed-in-user show --query "{displayName:displayName, id:id, userPrincipalName:userPrincipalName}"
```

## 2. List current PIM eligible assignments for a principal

```bash
# Using Azure CLI
az role eligibility-schedule list \
  --scope "$APPROVED_AZURE_SCOPE" \
  --query "[?principalId=='$PRINCIPAL_OBJECT_ID'].{roleName:roleDefinitionDisplayName, scope:scope, endDateTime:endDateTime}"
```

## 3. List active role assignments (not eligible — currently active)

```bash
az role assignment list \
  --assignee $PRINCIPAL_LOOKUP_VALUE \
  --scope "$APPROVED_AZURE_SCOPE" \
  --query "[].{role:roleDefinitionName, scope:scope, principalType:principalType}"
```

## 4. Check pending activation requests

```bash
az role assignment schedule request list \
  --scope "$APPROVED_AZURE_SCOPE" \
  --query "[?status=='PendingApproval' || status=='PendingAdminDecision'].{requestId:name, role:roleDefinitionDisplayName, requestor:requestorId, justification:justification}"
```

## 5. Verify audit log for recent activations

```bash
# Requires Entra ID audit log access
az monitor activity-log list \
  --resource-provider Microsoft.Authorization \
  --start-time $(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ) \
  --query "[?operationName.value contains 'roleAssignmentScheduleRequests'].{caller:caller, time:eventTimestamp, status:status.value}"
```

# Rollback Playbook: Azure Live PIM JIT Activation Guard

## Evidence-variable convention

Shell variables in examples are local operator placeholders from an approved change record or already configured shell context. Do not commit real values, and redact them from shared evidence unless disclosure is explicitly approved.

## Deactivate an active PIM role assignment immediately

```bash
# Find the active role assignment schedule instance to cancel
az role assignment schedule list \
  --scope "$APPROVED_AZURE_SCOPE" \
  --query "[?assignedTo=='$PRINCIPAL_OBJECT_ID'].{id:name, role:roleDefinitionDisplayName, endDateTime:endDateTime}"

# Submit a deactivation request
az role assignment schedule request create \
  --scope "$APPROVED_AZURE_SCOPE" \
  --role-definition-id $ROLE_DEFINITION_ID \
  --principal-id $PRINCIPAL_OBJECT_ID \
  --request-type SelfDeactivate
```

## Deny a pending approval request

PIM approval actions are performed via Entra ID portal or the PIM API:

```
PATCH https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{requestId}?api-version=2020-10-01
Body: { "properties": { "status": "Denied", "justification": "<reason>" } }
```

## Revoke an emergency break-glass access grant

```bash
# Remove the active role assignment
az role assignment delete \
  --assignee $PRINCIPAL_OBJECT_ID \
  --role $ROLE_DEFINITION_NAME \
  --scope "$APPROVED_AZURE_SCOPE"
```

After revoking, immediately review Azure Monitor activity log for actions taken
during the activation window and file an incident report.

## Rollback limitations

- Actions taken during an active PIM session cannot be undone by deactivating the role.
- Azure Activity Log retains actions for 90 days — preserve a log export for security review.
- PIM activation logs in Entra ID are retained per your Entra ID log retention settings.

# Safety Checklist

## Evidence labels

- `documentation-based`: grounded in Microsoft Learn or listed official documentation.
- `sampled-current-state`: grounded in read-only Azure observations from the user's configured tools.
- `user-provided`: grounded in sanitized snippets supplied by the user.
- `inference`: reasoned from evidence but not directly proven.

## Mutation boundary

- Default to read-only review.
- Do not perform create, update, delete, activate, approve, cancel, deactivate, migrate, cut over, route, peer, deploy, alert, suppress, or configuration changes unless the user explicitly asks and approval is clear.
- Prefer preview, assessment, status, list, show, query, activity-log, dependency, and diagnostic evidence before any mutation.

## Credential and data boundary

- Never ask users to paste credentials, tokens, tenant IDs, subscription IDs, customer data, private keys, appliance secrets, migration inventory dumps, log payload secrets, or raw environment dumps.
- Summarize sensitive evidence by field presence, control state, and risk; do not reproduce secret material.

## Risk gates

- Stop on ambiguous target, ambiguous principal, missing approval, missing owner, missing rollback, stale assessment, incomplete dependency mapping, unclear routing, or missing telemetry for high-impact assets.
- Separate documented product behavior from sampled configured-environment evidence.

## Asset-specific hard line

Never activate or approve PIM privileged access without confirming eligible principal, scope, role, activation duration, MFA/Conditional Access requirement, justification or ticket, approval status, and deactivation/expiry behavior.

# Workflow and Output Contract

## Execution flow

1. Scope the exact target, environment boundary, owner, requested decision, and evidence available.
2. Load `official-sources.md`, then the component operations guide for service behavior and risk gates.
3. Gather sampled read-only evidence only when available and safe.
4. Compare observed posture against documented behavior, least-privilege expectations, and operational safety rules.
5. Return a verdict with evidence level, blockers, safe next actions, and open questions.

## Required output

- `verdict`: pass, warn, fail, or blocked.
- `evidence_level`: documentation-based, sampled-current-state, user-provided, inference, or mixed.
- `scope`: what was reviewed and what was not reviewed.
- `blockers`: issues that prevent a safe or production-ready conclusion.
- `findings`: severity-labeled risks with source labels.
- `safe_next_actions`: reversible actions first; mutation only with explicit approval.
- `open_questions`: missing facts that would change the verdict.

## Stress checks

- What assumption would make this recommendation unsafe?
- Which identity, migration, network, telemetry, route, or dispatch decision has the largest blast radius?
- What evidence would disprove the claimed readiness?
- Is the answer accidentally treating documentation as configured-environment proof?

## Response discipline

Use Microsoft Learn documentation through the user's configured documentation MCP for documented Azure behavior. Use sampled read-only Azure evidence only for current configured-environment observations and label it as sampled evidence.