MSP guide — Shield DNS filtering & Sentinel safety monitoring

Overview

Shield is The One Stack's intelligent web protection platform built for K-12 schools and small businesses. As an MSP, you manage Shield on behalf of your school clients from the Hub at app.theonestack.com/shield. Shield has two products you can sell and operate together or separately:

• Shield DNS — Protects every device on the network by filtering domain lookups through a five-tier verdict engine. Handles CIPA/E-Rate compliance logging, SafeSearch enforcement, and a Chrome extension for off-network coverage. Included in the platform's per-user cost — Shield DNS is not priced per device.
• Shield Sentinel — Monitors student communications inside Google Workspace (Gmail, Drive, Chat; Microsoft 365 is on the roadmap) for safety concerns like self-harm, bullying, grooming, and violence. Every serious concern becomes an AI-assembled case file routed to the right counselor, administrator, and consented parent. Sold per student as an add-on.

You do everything from one interface: activate schools, set policy, review alerts, invite counselors, onboard parents, and run compliance reports. This guide walks through the day-to-day work.

Key Features

• Five-tier DNS verdict engine — Decisions flow through Redis cache, your allow/block lists, cross-MSP fleet consensus, live threat feeds (URLhaus, ThreatFox, PhishTank, OpenPhish, OTX), AI name analysis, and full-page crawl with AI verdict. Most lookups resolve in under 10ms from cache.
• Per-school policy — Each school client has its own CIPA mode, SafeSearch, YouTube restriction, blocked categories, allowed categories, and custom allow/block lists.
• CIPA compliance audit — Every block in a CIPA-relevant category (obscene content, material harmful to minors, child-safety concerns) is logged for E-Rate reporting, with a printable report endpoint.
• No per-video YouTube review — Shield does not offer a per-video YouTube review queue; that portion is retired. What a student can watch is governed by YouTube Restricted Mode (part of SafeSearch enforcement) and domain-level DNS rules, and the Chrome extension adds no per-video enforcement.
• Shared threat intelligence — When five or more MSPs across the platform confidently block a domain, every Shield tenant benefits automatically via the anonymized fleet-signal system.
• Sentinel 4-tier safety analysis — Student content is screened locally for keywords, then escalated through progressively stronger AI models. Only serious signals generate alerts.
• Case files assembled by AI — High-severity signals get a structured case file: summary, timeline, risk factors, counselor guidance, conversation starters, and recommended actions. No raw student content in the case file.
• THEO in the comment thread — Type @THEO in any alert comment to get a trauma-informed second opinion, a suggestion on language to use with a parent, or a summary of the student's prior alerts.
• Parent consent gating — Parents are never included in an alert's recipients until you or a school admin has confirmed COPPA/FERPA consent is on file. This is enforced in code.
• CSV bulk parent import — Upload a parent list, preview fuzzy-name matches against the student roster, confirm the ones that look right, and Shield fires magic-link invites automatically.
• Cross-MSP parent unification — When a parent has children in multiple schools under different MSPs, their parent portal shows all children in one view.

How To: Activate a New School Client

1. From the Hub, open the school's client record and launch the Shield activation wizard.
2. Enter the school's public details: display name, logo URL (upload to blob storage first and paste the HTTPS link), and a short URL slug (letters, numbers, hyphens only, 3-50 characters). This slug powers the white-labeled parent login page at app.theonestack.com/portal/shield/<slug>.
3. Choose CIPA mode. K-12 schools should leave this on — it turns on the audit log required for E-Rate funding.
4. Tick the consent-confirmed box to certify the school has authorized monitoring per COPPA/FERPA.
5. Submit. Shield creates the org-settings row, client config (CIPA on by default), Sentinel config, and any custom block-list entries you seeded — all in one transaction.
6. Once saved, the slug is locked permanently. Pick carefully.

How To: Set Up DNS Filtering

1. Retrieve the Shield DNS resolver IPs from the onboarding panel (there's a dedicated endpoint that shows IPv4, IPv6, DNS-over-HTTPS, and DNS-over-TLS addresses).
2. Point the school's network DNS to those resolvers — either by setting the school router's upstream DNS, by deploying the Shield DNS agent, or by installing the Chrome extension on student devices.
3. Under the client's config, choose which categories to block and which to explicitly allow. Common K-12 blocks: adult content, gambling, weapons, social media (optional), streaming (optional).
4. If the school is in E-Rate territory, leave CIPA mode on. Leave SafeSearch and YouTube restricted mode on too unless there's a specific reason to disable them.
5. There is nothing to configure for a per-video YouTube review — Shield does not offer one. YouTube content is governed by YouTube Restricted Mode (SafeSearch enforcement) and your domain-level DNS rules.

How To: Manage Allow and Block Lists

• Global lists — Managed by The One Stack platform owners. These contain Microsoft 365 endpoints, major CDNs, Tranco top-domain placeholders, and the live threat-intel feeds. You cannot edit global lists unless you have platform-owner flag set.
• MSP lists — Apply to every client under your MSP. Use these for partners, vendors, or services you trust across your customer base.
• Client lists — Apply only to one school. Use these for district-specific approvals or bans.

To add an entry, open the Lists tab, choose the scope, enter the domain, and add a short reason so future you or your colleagues know why it exists. Shield invalidates the Redis verdict cache for that domain immediately so the new rule takes effect on the next lookup.

How To: Connect a School's Google Workspace for Sentinel

Sentinel needs read access to Gmail, Drive, Google Chat, and Classroom rosters. You use your own Google Cloud project's OAuth credentials — never a school's.

1. In your MSP's Google Cloud Console, create an OAuth 2.0 client ID with redirect URI set to https://api.theonestack.com/api/v1/shield/sentinel/connect/callback.
2. Copy the client ID and client secret. Paste them into the Shield UI's Sentinel Connect panel alongside the school's client ID.
3. Shield stores both values encrypted (AES-256-GCM) and returns an authorization URL.
4. Send that URL to the school's Google Workspace super admin. They sign in, consent to the scopes, and Google redirects back to Shield.
5. Shield exchanges the auth code for access and refresh tokens, encrypts them, and enables Sentinel scanning for that client. A scan runs automatically every 15 minutes from then on.

To disconnect a school, hit the delete action on the Connections panel. The connection is disabled and scans stop; historical signals remain for compliance reference.

How To: Add Counselors and Staff

Shield has four school-side roles. Each maps to a different portion of what a user can see and do:

To invite a counselor or staff member, use the Hub user management flow and assign the appropriate tpl_client_shield_* role template scoped to the school's client ID. They receive a magic-link email, set a password on first login, and land in the school portal.

How To: Import Students

Students enter Shield one of two ways:

• Automatic discovery — Every time Sentinel analyzes a message, it hashes the sender and recipient emails and creates a roster entry for any hash it hasn't seen before. Display names default to the first name or a sanitized "Student 042" placeholder.
• Bulk roster import (optional) — Upload a CSV ahead of time if the school wants known students visible before any signal fires.

Student emails are never stored in cleartext. Every student record keys on a SHA-256 hash of the email address, which means the roster view shows display names or hash prefixes, not real addresses.

How To: Invite Parents and Link Them to Students

Single invite:

1. From the school's Parents tab, click Add Parent.
2. Enter the parent's email, name, optional phone, relationship (mother, father, guardian, legal custodian), and their preferred notification channel (email and/or SMS).
3. Optionally paste one or more student emails to pre-link the parent. Shield hashes each email and links only to students already in the school's roster. Non-matching entries are silently dropped — a parent at School A cannot be linked to a student at School B.
4. Click Invite. Shield publishes an invite event; the Hub notification worker provisions a parent user account and sends a magic-link email.

Bulk CSV import:

1. Under the Parents tab, choose Import from CSV.
2. Upload a file with columns for parent email, parent name, parent phone (optional), student email (preferred) or student name, and relationship. Up to 5000 rows per session.
3. Shield previews every row. Exact email matches against the roster show as "exact." Name-only rows get up to three fuzzy matches (normalized Levenshtein, 55/100 minimum score). Unmatched rows show as "none."
4. Review the preview. For each row you can accept the auto-match, pick a different candidate, or skip.
5. Confirm. Shield upserts the parent rows, links them to the validated students, and fires invite events for each new parent.

Import sessions expire automatically: preview sessions after seven days, confirmed sessions after thirty days.

How To: Verify Parent Consent

Before a parent is ever included in an alert's recipients, someone has to mark their record as consent-verified. This is the COPPA/FERPA safeguard and it is enforced in the alert dispatcher — an unverified parent is silently dropped from the recipient list even on a tier 3 alert.

1. Confirm the school has a signed consent form on file.
2. Open the parent's record in the Parents tab.
3. Toggle Consent Verified to on.
4. Save.

From that point forward, the parent is included as a recipient for alerts at whatever tier the school's notify-parents threshold is set to. Sentinel's destination today is the alert row — it appears in the Sentinel alert inbox the counselor dashboard reads and, for the parent, in the parent portal; no email, SMS, push or page is sent.

How To: Configure Notification Tiers

Every Sentinel signal gets a tier from 0 to 3:

• Tier 0 (Noise) — No alert fires. Keyword matched but AI determined there's no genuine concern, or sentiment was neutral/positive.
• Tier 1 (Monitor) — Logged for trend analysis. The counselor recipient list is the default.
• Tier 2 (Alert) — Counselor-level concern. The counselor team is the default recipient group.
• Tier 3 (Critical) — Immediate concern. Counselors and school admins are the recipients. Parents who are consent-verified are included if the school's parent-notify threshold is set to 3 or lower. The alert appears in the Sentinel alert inbox the counselor dashboard reads and, for a linked parent, in the parent portal; no email, SMS, push or page is sent.

To change a school's thresholds:

1. Open the Sentinel Config panel for the client.
2. Set notify_parents_on_tier to 1, 2, or 3. The system default is 3, so parents are included only for critical alerts unless a school lowers the threshold. Setting it to 2 includes parents for counselor-level concerns as well; setting it to 1 includes parents for every real signal.
3. Add or remove email addresses from the tier-2 counselor recipient list and tier-3 admin recipient list.
4. Toggle the weekly parent digest on or off and pick which day of the week it is generated for (default Friday). ⚠️ The digest is defined and never invoked: the generator exists (generateParentDigest) but nothing calls it and no scheduled job runs it, so no digest is produced for any client, enabled or not — it is not emailed to parents today.
5. Save.

How To: Manage Alerts

1. Open the Alerts tab. You see every alert across all your schools, with filters for status, tier, and client.
2. Click an alert to see the case file: summary, timeline snippets, evidence references, risk factors, counselor guidance, conversation starters, and recommended actions.
3. The comment thread at the bottom is a chronological conversation between MSP staff, school staff, consented parents, the system, and THEO. Use it to coordinate response.
4. Acknowledge the alert when someone has taken ownership. Resolve it when the intervention is complete, adding resolution notes.
5. If the alert is genuinely not a concern (sibling joking, classroom exercise, song lyric), mark it False Positive. Shield publishes this to the training pipeline so the model learns from it.

How To: Use @THEO in an Alert Thread

THEO is the platform's AI assistant, embedded directly in Shield's alert comment threads. To invoke it, mention @THEO in your comment body and set the mention flag. Shield sends THEO the alert, the last 20 comments, and metadata on the student's prior 10 alerts — metadata only, never the original message content. THEO responds based on whether the triggering author is a parent (warm, non-clinical tone) or staff (professional, trauma-informed), and its reply is visible to everyone authorized on the thread.

THEO is useful for:

• "What should I say to this parent?"
• "Summarize this student's alert history."
• "What are the warning signs I should watch for next?"
• "Draft a follow-up email for the counselor."

THEO's comments are never editable or deletable — they are part of the audit trail.

How To: Run a CIPA Compliance Report

1. From the client's dashboard, open the CIPA Report panel.
2. Select a date range. The maximum span per report is 400 days.
3. Generate. Shield returns a structured report showing all blocks in CIPA categories (obscene, harmful to minors, child safety) over the period.
4. The portal downloads the report as a printable HTML document. Shield serves the report as JSON and does not generate or serve a PDF — a PDF is only what your browser's print-to-PDF ("Save as PDF" in the print dialog) makes from that document. The Reports panel separately exports the underlying query data as CSV.

For a raw audit log, use the CIPA Audit panel, which paginates every CIPA-category block with domain, device, and timestamp.

How To: Review Billing

The Billing panel shows:

• 30-day unique device count — Shield DNS usage. Shield DNS is included in the platform's per-user cost, so this count is not billed per device.
• 30-day unique monitored student count — this drives the Sentinel add-on.
• The monthly total.

The only Shield add-on:

• Sentinel add-on: $0.50 per monitored student per month.

Internal dogfood orgs (porg_jpthegeek, porg_theone) have billing zeroed automatically.

Frequently Asked Questions

Do we have to sell DNS and Sentinel together? No. Sell either product on its own or both together. Sentinel is an add-on to your Shield subscription, not a prerequisite.

Whose Google OAuth project do we use for Sentinel? Yours. Each MSP supplies its own Google Cloud project's OAuth client ID and secret. Shield encrypts and stores them per school. Schools never see or manage OAuth credentials directly.

What happens to raw student emails and message bodies? They are never persisted. Sentinel fetches content into memory, analyzes it, and discards the raw content as soon as analysis finishes. Only SHA-256 hashes and analysis metadata reach the database.

Can a parent see another student's alerts? No. Parents are authorized against the specific student hashes linked in the parent-to-student table. Every alert-detail and comment-read endpoint verifies the link before returning data.

Can we share a block-list between schools? Yes. Use the MSP-scope list for entries that apply to every school you manage, and client-scope lists for school-specific entries.

What is "fleet signal" and why does it matter? Fleet signals are anonymized cross-MSP consensus. When a domain gets confidently blocked by five or more MSPs with 0.9+ confidence, Shield starts blocking it everywhere without re-running AI analysis. Every MSP benefits from every other MSP's research, but no MSP's specific block history is ever exposed — the only key is a SHA-256 hash of the domain.

How fast does a DNS query resolve? Cached verdicts return in under 10ms. Tier 1 feed lookups usually complete in under 300ms. Tier 2 AI analysis runs around a second. Tier 3 with a full-page crawl can take 10-20 seconds, but this only happens for genuinely novel domains; the vast majority of traffic is cache hits or Tier 1 verdicts.

What if we need to block a domain right now? Add it to the client or MSP blocklist. Shield invalidates the Redis cache for that domain immediately; the next DNS query for it will hit the new rule.

Does Sentinel scan Microsoft 365? Not yet. The ingestion layer is scaffolded for M365 but only Google Workspace is live. Microsoft 365 support is on the roadmap.

What about students who turn 18 or parents who want their child removed from monitoring? Use the student opt-out flow on the Students tab. This is the FERPA 18-plus opt-out path. Shield stops generating signals for that student going forward.

Troubleshooting

Parents aren't included in alerts they expected. Check three things, in order:

1. Is their consent_verified flag set to true? This is the most common cause — it is required by law and enforced in code.
2. Is the school's notify_parents_on_tier set higher than the alert's tier? A threshold of 3 means tier-2 alerts do not include parents.
3. Is the parent linked to the student, and does their record carry a channel preference (notify_email / notify_sms)?

Note that no tier of the Sentinel pipeline sends an email, SMS, push or page today — the alert row is the destination, read from the Sentinel alert inbox and the parent portal.

A school admin reports that alerts aren't firing even though there's clearly concerning content. Verify the Sentinel connection is still active — the OAuth tokens refresh automatically, but if Google revokes consent (password reset, admin change) the connection goes inactive. Reconnect from the Connections panel.

The school slug I want is taken. Slugs are globally unique across the platform. Use the slug-availability check endpoint before committing. Once a slug is saved, it is locked and cannot be changed — choose carefully.

A DNS query is being blocked and shouldn't be. Look up the domain under the Verdicts tab to see which tier flagged it, the source, and the reason. If the verdict is wrong, add the domain to the client or MSP allowlist and Shield invalidates the cache immediately. You can also submit an unblock request from the Requests panel.

A Sentinel CSV import says "no matches" for rows that clearly should match. The fuzzy matcher needs a minimum score of 55 out of 100. Check that the names in your CSV are close to what the school's Google Workspace has (diacritics, nicknames vs. legal names, last-name-first ordering). You can still confirm "none" rows manually by editing the parent record after import and adding student links by email.

The activation wizard returns a 409 Conflict on the slug field. Another org already owns that slug. Pick a different one.

THEO replied with "THEO is temporarily unavailable." The THEO service timed out, returned a non-2xx, or is unreachable. Shield always writes the fallback comment so the thread moves forward. Try again in a minute; if it persists, check THEO service health.

DNS queries are being rate-limited. Shield caps /dns/query at 600 requests per minute per org. A busy school with hundreds of devices should be fine, but a misconfigured agent looping on failures can hit this ceiling. Check agent logs for retry storms and confirm each device has a stable device_id so caching works.