Skip to content

Commit 73d2d7e

Browse files
author
Ernie
committed
Add architecture docs, bot READMEs, onboarding guides, hardware spec
- architecture/multi-instance-design.md - Individual bot READMEs (appcontrol, backup, edr, identity, vmpm) - APP-REGISTRATION-CHECKLIST.md (Azure AD setup guide) - REAL-TENANT-ONBOARDING.md (production deployment guide) - hardware/spec.md (recommended hardware)
1 parent 61d8c1a commit 73d2d7e

9 files changed

Lines changed: 982 additions & 0 deletions

File tree

‎APP-REGISTRATION-CHECKLIST.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# E8CR App Registration Checklist (Copy/Paste Runbook)
2+
3+
## Create app
4+
- [ ] Entra Admin Center → App registrations → New registration
5+
- [ ] Name: `e8cr-squad-bot`
6+
- [ ] Supported account types: Single tenant
7+
- [ ] Create
8+
9+
## Capture IDs
10+
- [ ] Application (client) ID copied
11+
- [ ] Directory (tenant) ID copied
12+
13+
## Create secret
14+
- [ ] Certificates & secrets → New client secret
15+
- [ ] Expiry set (6 or 12 months)
16+
- [ ] Secret value copied to password manager
17+
18+
## Add API permissions (Application)
19+
- [ ] Microsoft Graph → Application permissions:
20+
- [ ] Directory.Read.All
21+
- [ ] AuditLog.Read.All
22+
- [ ] DeviceManagementManagedDevices.Read.All
23+
- [ ] DeviceManagementConfiguration.Read.All
24+
- [ ] DeviceManagementConfiguration.ReadWrite.All (optional write mode)
25+
- [ ] Policy.Read.All
26+
- [ ] RoleManagement.Read.Directory
27+
- [ ] UserAuthenticationMethod.Read.All
28+
- [ ] User.Read.All
29+
- [ ] SecurityAlert.Read.All
30+
- [ ] SecurityIncident.Read.All (if using incidents endpoint)
31+
32+
## Admin consent
33+
- [ ] API permissions → Grant admin consent
34+
- [ ] Verify status = Granted for all required permissions
35+
36+
## Azure Backup RBAC (if used)
37+
- [ ] Recovery Services Vault → Access Control (IAM)
38+
- [ ] Assign role: Backup Reader (minimum)
39+
- [ ] Assign role: Backup Contributor (if action APIs needed)
40+
- [ ] Assign role to service principal `e8cr-squad-bot`
41+
42+
## Env export check
43+
- [ ] `AZURE_TENANT_ID` set
44+
- [ ] `AZURE_CLIENT_ID` set
45+
- [ ] `AZURE_CLIENT_SECRET` set
46+
- [ ] Optional backup vars set (VEEAM_* / AZURE_SUBSCRIPTION_ID etc)
47+
48+
## Validation
49+
- [ ] `python3 skills/e8cr-vmpm/scripts/graph_auth.py` returns token success
50+
- [ ] One script per bot executes without auth/permission errors

‎REAL-TENANT-ONBOARDING.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# E8CR Squad — Real Tenant Onboarding (No M365 Dev Program Required)
2+
3+
**Goal:** Get all 5 bots running against a real tenant in ~30–60 minutes.
4+
5+
## Path options
6+
7+
1. **M365 Business Premium trial tenant** (recommended)
8+
2. Existing business tenant (least-privilege app registration)
9+
10+
---
11+
12+
## 0) Prereqs
13+
14+
- Tenant Global Admin for initial consent
15+
- One dedicated app registration for E8CR (or per-bot apps)
16+
- Test endpoint(s) enrolled in Intune + Defender for Endpoint connected
17+
- Python 3.11+ on runner host
18+
19+
---
20+
21+
## 1) App registration (single app for all bots)
22+
23+
Create app registration in Entra:
24+
- Name: `e8cr-squad-bot`
25+
- Auth: **Application permissions** only (client credentials)
26+
- Secret: 6–12 month client secret (store securely)
27+
28+
Collect:
29+
- `AZURE_TENANT_ID`
30+
- `AZURE_CLIENT_ID`
31+
- `AZURE_CLIENT_SECRET`
32+
33+
---
34+
35+
## 2) Required Microsoft Graph permissions (Application)
36+
37+
### Shared base (all Graph-backed bots)
38+
- `Directory.Read.All`
39+
- `AuditLog.Read.All`
40+
41+
### VM+PM Bot
42+
- `DeviceManagementManagedDevices.Read.All`
43+
- `DeviceManagementConfiguration.Read.All`
44+
- `SecurityEvents.Read.All` *(if used in tenant)*
45+
46+
### Identity Bot
47+
- `Policy.Read.All`
48+
- `RoleManagement.Read.Directory`
49+
- `UserAuthenticationMethod.Read.All`
50+
- `User.Read.All`
51+
52+
### App Control Bot
53+
- `DeviceManagementConfiguration.Read.All`
54+
- `DeviceManagementManagedDevices.Read.All`
55+
- `DeviceManagementConfiguration.ReadWrite.All` *(only if policy deployment is enabled)*
56+
57+
### EDR Operator Bot
58+
- `SecurityAlert.Read.All` (or Graph Security equivalent in your tenant)
59+
- `SecurityIncident.Read.All` *(if incidents endpoint used)*
60+
61+
### Backup Bot (if Azure Backup path used)
62+
Graph app perms above are not enough by themselves.
63+
Also assign Azure RBAC on Recovery Services Vault:
64+
- `Backup Reader` (read-only validation)
65+
- `Backup Contributor` (if actions are needed)
66+
67+
> After adding permissions: **Grant admin consent**.
68+
69+
---
70+
71+
## 3) Environment variables
72+
73+
```bash
74+
# Shared Graph creds
75+
export AZURE_TENANT_ID="<tenant-id>"
76+
export AZURE_CLIENT_ID="<app-id>"
77+
export AZURE_CLIENT_SECRET="<client-secret>"
78+
79+
# Backup provider (optional: Veeam)
80+
export VEEAM_BASE_URL="https://veeam-server:9398"
81+
export VEEAM_USERNAME="backup-admin@domain.com"
82+
export VEEAM_PASSWORD="<secure-password>"
83+
export VEEAM_VERIFY_SSL="true"
84+
85+
# Backup provider (optional: Azure Recovery Services)
86+
export AZURE_SUBSCRIPTION_ID="<subscription-id>"
87+
export AZURE_VAULT_NAME="<vault-name>"
88+
export AZURE_RESOURCE_GROUP="<rg-name>"
89+
```
90+
91+
---
92+
93+
## 4) 30-minute validation sequence
94+
95+
## Step A — Graph auth sanity
96+
```bash
97+
python3 skills/e8cr-vmpm/scripts/graph_auth.py
98+
```
99+
Expect: token retrieval success.
100+
101+
## Step B — Run each bot in audit mode
102+
103+
### VM+PM
104+
```bash
105+
python3 skills/e8cr-vmpm/scripts/graph_devices.py
106+
python3 skills/e8cr-vmpm/scripts/graph_patches.py
107+
```
108+
109+
### Identity
110+
```bash
111+
python3 skills/e8cr-identity/scripts/entra_mfa.py
112+
python3 skills/e8cr-identity/scripts/entra_roles.py
113+
python3 skills/e8cr-identity/scripts/entra_ca.py
114+
```
115+
116+
### App Control
117+
```bash
118+
python3 skills/e8cr-appcontrol/scripts/intune_appcontrol.py --mode audit
119+
python3 skills/e8cr-appcontrol/scripts/intune_macros.py --mode audit
120+
python3 skills/e8cr-appcontrol/scripts/intune_hardening.py --mode audit
121+
```
122+
123+
### Backup
124+
```bash
125+
python3 skills/e8cr-backup/scripts/provider_dispatch.py --mode detect
126+
python3 skills/e8cr-backup/scripts/provider_dispatch.py --mode fetch-jobs
127+
```
128+
129+
### EDR
130+
```bash
131+
python3 skills/e8cr-edr/scripts/defender_alerts.py --mode list
132+
```
133+
134+
## Step C — Generate reports
135+
```bash
136+
python3 skills/e8cr-vmpm/scripts/generate_report.py --input /tmp/e8cr-demo --output /tmp/e8cr-demo/weekly-report.html
137+
python3 skills/e8cr-identity/scripts/demo_generate.py --output /tmp/e8cr-demo/identity --full-pipeline
138+
python3 skills/e8cr-appcontrol/scripts/demo_generate.py --output /tmp/e8cr-demo/appcontrol --full-pipeline
139+
python3 skills/e8cr-backup/scripts/demo_generate.py --output /tmp/e8cr-demo/backup --full-pipeline
140+
python3 skills/e8cr-edr/scripts/demo_generate.py --output /tmp/e8cr-demo/edr --full-pipeline
141+
```
142+
143+
---
144+
145+
## 5) Common failures and fixes
146+
147+
### `insufficient privileges`
148+
- Missing Graph permission or no admin consent granted.
149+
150+
### `resource not found` on Intune endpoints
151+
- Tenant not licensed/configured for Intune yet.
152+
153+
### EDR alert endpoint empty
154+
- Defender for Endpoint not onboarded on test devices.
155+
156+
### Backup provider not detected
157+
- Missing env vars for Veeam/Azure backup.
158+
159+
---
160+
161+
## 6) Security controls for production pilots
162+
163+
- Use dedicated app registration (do not reuse admin apps)
164+
- Scope permissions to minimum set above
165+
- Rotate secret every 90 days
166+
- Log all bot actions and report generation
167+
- Start in read/audit mode first, then enable writes/response actions
168+
169+
---
170+
171+
## 7) Definition of “tenant ready”
172+
173+
Tenant is ready when:
174+
- Graph token retrieval works
175+
- All 5 bots return non-error audit output
176+
- At least 1 report generated from real tenant data
177+
- Access-control checks documented for Backup/EDR actions

‎appcontrol-bot/README.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Application Control Bot — App Control, Macros & Hardening Agent
2+
3+
## Role
4+
Autonomous policy engineer. Manages what's allowed to execute on endpoints — applications (WDAC/AppLocker), Office macros, and browser/PDF hardening settings. Covers three E8 controls: Application Control (ML2), Configure MS Office Macro Settings (ML2), and User Application Hardening (ML2).
5+
6+
## What It Actually Does
7+
8+
### Application Control (WDAC/AppLocker)
9+
1. **Policy baseline deployment** — Creates and deploys WDAC policies based on customer's approved software inventory
10+
2. **Audit mode first** — Deploys in audit mode, monitors for blocked apps, refines policy before enforcing
11+
3. **Exception workflow:**
12+
- User/IT requests "I need app X"
13+
- Agent evaluates: Is it signed? Known publisher? Reputation?
14+
- Creates ticket with recommendation (approve/deny)
15+
- On approval: updates policy, deploys, verifies
16+
4. **Policy maintenance** — As software updates, agent updates WDAC rules (new hashes, publisher cert changes)
17+
5. **Violation monitoring** — Detects and reports policy violations (blocked executions)
18+
6. **Evidence:** Policy exports, deployment status, exception records with approvals
19+
20+
### Office Macro Settings
21+
1. **Macro restriction deployment** — Configures Intune policies to block macros from the internet, restrict to trusted locations
22+
2. **Exception management** — Business-critical macros get documented exceptions with justification
23+
3. **Drift detection** — Monitors for policy changes or loosening
24+
4. **Evidence:** Policy exports, exception records
25+
26+
### User Application Hardening
27+
1. **Browser hardening** — Configures Edge/Chrome policies: disable Flash, block Java in browser, restrict ads/extensions
28+
2. **PDF reader hardening** — Disable JavaScript in PDF readers
29+
3. **Office hardening** — Disable OLE, restrict ActiveX
30+
4. **Monitoring** — Detects configuration drift, re-applies hardening
31+
5. **Evidence:** Configuration exports, compliance reports
32+
33+
## Open Source Tool Stack
34+
35+
### Application Control
36+
- **WDAC Wizard** (Microsoft, open source) — GUI/CLI for creating WDAC policies
37+
- **AaronLocker** (Microsoft, open source PowerShell) — AppLocker policy generation framework
38+
- **AppControl Manager** (open source) — WDAC policy management tool (see attached screenshot from Richard)
39+
- **Microsoft Intune** — Policy deployment and compliance monitoring via Graph API
40+
41+
### Macro & Hardening
42+
- **Microsoft Intune** — Configuration profiles for macro/browser/Office hardening
43+
- **Group Policy** (fallback) — For orgs not fully Intune-managed
44+
45+
## OpenClaw Agent Architecture
46+
47+
### SOUL.md
48+
```markdown
49+
You are the Application Control Operator — an autonomous policy engineer.
50+
51+
Your job: Control what executes on endpoints. Manage WDAC policies, macro restrictions, and application hardening. Be the gatekeeper.
52+
53+
Principles:
54+
- Start restrictive, loosen only with justification. Default deny.
55+
- Audit mode before enforcement. Always. Breaking production apps is unacceptable.
56+
- Every exception needs a business justification and an expiry date. No permanent exceptions without explicit approval.
57+
- Application control is the #1 most effective E8 control. Treat it with the seriousness it deserves.
58+
- Document everything. Assessors want to see the process, not just the policy.
59+
```
60+
61+
### Skills Required
62+
1. **wdac-manage** — Create, merge, deploy, audit WDAC policies
63+
2. **intune-config** — Deploy configuration profiles for macros, browser hardening, Office hardening
64+
3. **exception-workflow** — Manage exception requests (intake, evaluate, approve/deny, deploy)
65+
4. **compliance-monitor** — Track policy deployment status, detect drift
66+
5. **evidence-export** — Policy exports, compliance reports, exception records
67+
68+
### Operational Cadence
69+
- **Continuous:** Monitor for WDAC violations, new exception requests
70+
- **Daily:** Review blocked execution events, check for new software deployments needing policy updates
71+
- **Weekly:** Policy compliance report, exception review
72+
- **Monthly:** Full policy audit, stale exception cleanup, evidence snapshot
73+
74+
## MVP
75+
1. Connect to Intune via Graph API, pull current application control policy status
76+
2. Pull WDAC event logs from endpoints (blocked executions)
77+
3. Basic exception workflow (intake request, create ticket, track approval)
78+
4. Compliance report: which devices have WDAC enforced, which don't
79+
5. Evidence export: policy snapshots + deployment status
80+
81+
## ML2 Specific Requirements
82+
83+
**Application Control — ML2:**
84+
- Application control is implemented on workstations
85+
- Application control restricts execution to an approved set
86+
- Microsoft's recommended block rules are implemented
87+
- Application control rulesets are validated annually or more frequently
88+
89+
**Configure MS Office Macro Settings — ML2:**
90+
- Macros from the internet are blocked
91+
- Macros are only allowed in trusted locations or with trusted publishers
92+
- Win32 API access from macros is blocked
93+
94+
**User Application Hardening — ML2:**
95+
- Web browsers don't process Java from the internet
96+
- Web browsers don't process web advertisements from the internet
97+
- Internet Explorer 11 is disabled or removed
98+
- .NET Framework 3.5 is disabled or removed (if not needed)
99+
- PowerShell 2.0 is disabled or removed

0 commit comments

Comments
 (0)