DRIVESecurity Auditor

You need the gws CLI installed and authenticated with an account that has read access to Drive files and the Admin Reports API for audit logs. If you're a Workspace admin, your account already has this. If not, you'll need delegated admin credentials.

Critical: scope the agent's permissions tightly. This agent needs broad read access but should have zero write access to Drive permissions during normal scanning. Write access is only needed for the remediation phase, and that should be gated behind the human approval step. Create a dedicated service account with read-only Drive and Admin SDK scopes for scanning, and a separate credential set with write scope that's only invoked after human approval. If the agent's read-only credentials are compromised or the agent hallucinates, it can't modify anything.

# Install the CLI
npm install -g @googleworkspace/cli

# Set up auth with your admin account
gws auth setup

# Login — use a dedicated audit service account, not your personal admin
gws auth login

Test your access by running gws drive files list --params '{"pageSize": 5}' and gws admin activities list --params '{"userKey": "all", "applicationName": "drive", "maxResults": 3}'. If both return data, you're set. Then link the skills:

# Clone the repo and link the relevant skills
git clone https://github.com/googleworkspace/cli.git
ln -s $(pwd)/cli/skills/gws-drive ~/.openclaw/skills/
ln -s $(pwd)/cli/skills/gws-admin ~/.openclaw/skills/
ln -s $(pwd)/cli/skills/gws-gmail ~/.openclaw/skills/
ln -s $(pwd)/cli/skills/gws-sheets ~/.openclaw/skills/
ln -s $(pwd)/cli/skills/gws-shared ~/.openclaw/skills/

Credential hygiene: Rotate the agent's OAuth tokens on a regular schedule. Store credentials outside the agent's working directory — use environment variables or a secrets manager, not a config file the agent can read and potentially leak in its output. Monitor the service account's activity in the Admin console for any unexpected API calls. The agent running your security audit is itself a high-value target — treat it accordingly.

Create an audit.md prompt file that walks the agent through a four-phase scan. Each phase builds on the last, so ordering matters.

Phase 1 — Targeted discovery. Don't crawl every file and filter afterward — use the Drive API's query capabilities to go directly to the problem. The API supports visibility filters that surface the most dangerous shares without scanning your entire Drive:

# Find all "anyone with the link" shares — the highest-risk category
gws drive files list --params '{
  "q": "visibility = '\''anyoneWithLink'\'' or visibility = '\''anyoneCanFind'\''",
  "pageSize": 100,
  "fields": "nextPageToken,files(id,name,mimeType,owners,permissions(emailAddress,role,type,domain,expirationTime),sharingUser,createdTime,modifiedTime,webViewLink)",
  "includeItemsFromAllDrives": true,
  "supportsAllDrives": true
}'

This single query gets you every publicly linkable file in scope without touching the thousands of properly shared internal files. For user-level external shares (specific external email addresses with access), use the Admin SDK's Reports API to query Drive activity and audit logs — this is far more efficient than crawling permissions file by file:

# Query external sharing events from the audit log
gws admin activities list --params '{
  "userKey": "all",
  "applicationName": "drive",
  "eventName": "change_user_access",
  "filters": "target_domain!=yourcompany.com",
  "maxResults": 200
}'

Between the targeted Drive query and the Admin audit log, you'll have a complete picture of external exposure without ever doing a full file crawl.

Phase 2 — Enrich with access logs. Permissions alone don't tell you if a share is actively used or forgotten. The Admin SDK Reports API fills this gap:

# Pull Drive access events for a flagged file
gws admin activities list --params '{
  "userKey": "all",
  "applicationName": "drive",
  "eventName": "view",
  "maxResults": 200,
  "filters": "doc_id==FILE_ID"
}'

For each flagged file from Phase 1, check the access logs. A file shared with "anyone with the link" that was last accessed 14 months ago is a different risk profile than one accessed daily by 30 external users. The access data lets your agent distinguish between stale exposure (forgot to revoke) and active exposure (someone is using this right now), which directly affects remediation urgency.

Phase 3 — Classify. This is where the agent earns its keep. For each externally shared file, assign a risk tier — but don't rely on naive keyword matching against file titles. A file called "Salary Research for Blog Post" isn't sensitive. A file called "Q2 projections" containing actual financial data is.

For organizations on Google Workspace Enterprise, use Drive labels as your primary classification signal. If your team has already labeled files as "Confidential," "Internal Only," or "Public," the agent should respect those labels as ground truth — they represent a human decision about sensitivity.

For deeper inspection, integrate with Google's DLP (Data Loss Prevention) API, which can scan file contents for sensitive patterns — credit card numbers, SSNs, API keys, medical records — far more reliably than title matching:

# DLP content inspection for a flagged file
gws drive files export \
  --params '{"fileId": "FILE_ID", "mimeType": "text/plain"}' \
  | gws dlp content inspect --params '{
    "inspectConfig": {
      "infoTypes": [
        {"name": "CREDIT_CARD_NUMBER"},
        {"name": "US_SOCIAL_SECURITY_NUMBER"},
        {"name": "EMAIL_ADDRESS"},
        {"name": "GCP_API_KEY"}
      ],
      "minLikelihood": "LIKELY"
    }
  }'

Combine the signals into risk tiers:

• Critical — File has DLP findings (sensitive content confirmed) AND is shared with anyone or a personal email domain, OR has a "Confidential" Drive label and is externally shared
• High — File is shared with anyone with the link regardless of content, OR is shared externally with edit/write access, OR DLP finds sensitive patterns in a file shared with specific external users
• Medium — File is shared with a specific external email address with view-only access, share is older than 90 days, and access logs show no external access in the last 60 days (stale share)
• Low — File is shared with a known vendor or partner domain on your allowlist, OR is explicitly labeled "Public" via Drive labels

Include an allowlist section in your prompt for trusted external domains — agencies, legal counsel, long-term partners. Without this, every legitimate vendor share becomes noise.

For organizations on Business plans without access to DLP or Drive labels, fall back to a layered heuristic: combine permission type (anyone vs. specific user), access level (editor vs. viewer), share age, access log activity, and file location (is it in a folder named "HR" or "Legal"?). This is noisier than DLP but still far better than title keyword matching alone.

Phase 4 — Report and queue. The agent compiles findings into two outputs. First, a summary email grouped by risk tier with counts and the top 10 most critical items, sent to your security team. Second — and this is essential — a detailed Sheets log that serves as the approval queue for any remediation actions.

# Log a flagged file to the audit spreadsheet
gws sheets +append --spreadsheet-id AUDIT_SHEET_ID --range 'Findings' \
  --values '["2026-03-07","Q2 Financials.xlsx","finance-team@company.com","contractor@gmail.com","editor","anyone_with_link","CRITICAL","DLP: 3 SSN matches","PENDING REVIEW","Revoke anyone-with-link, restrict to domain"]'

# Send the summary report
gws gmail +send --to security-team@company.com \
  --subject 'Weekly Drive Audit — March 7 — 14 Critical, 38 High' \
  --body "$REPORT_SUMMARY"

The Sheets log includes a "Status" column (PENDING REVIEW / APPROVED / REJECTED / REMEDIATED) and a "Proposed Action" column. The agent never modifies permissions directly. It proposes changes and waits for human approval. This is the most important design decision in the entire blueprint.

Schedule the audit to run weekly. Sundays work well — the report is waiting Monday morning when your security or IT team starts their week. A cron like 0 3 * * 0 runs it at 3 AM Sunday.

The first run will be noisy. Expect a long list of "critical" findings that are actually fine — the CFO sharing a budget doc with your external accountant, the marketing team sharing a deck with an agency. This is normal. After the first run, update your prompt's allowlist with the trusted domains and specific email addresses that surfaced as false positives.

By the third run, your signal-to-noise ratio should be solid. The real wins are the shares you didn't know about: the departed contractor who still has edit access to a product roadmap, the "anyone with the link" share on an HR document from 18 months ago, the intern's personal Gmail with access to the engineering shared drive.

The remediation loop: Your security team reviews the Sheets approval queue, marks rows as APPROVED or REJECTED, and a second scheduled run (daily, lightweight) picks up approved rows and executes the permission changes using a separate write-scoped credential. This human-in-the-loop step is non-negotiable. We've seen OpenClaw agents act outside their instructions — a Meta security researcher's agent deleted her entire inbox despite explicit "confirm before acting" guardrails. An agent with domain-wide Drive write access that hallucinates a remediation action could revoke access to files people are actively using. The approval queue eliminates this class of failure entirely.

# Remediation agent (separate cron, separate credentials with write access)
# Only processes rows marked APPROVED in the Sheets queue

# Revoke an anyone-with-link permission
gws drive permissions delete \
  --params '{"fileId": "FILE_ID", "permissionId": "anyoneWithLink"}'

# Downgrade an external editor to viewer
gws drive permissions update \
  --params '{"fileId": "FILE_ID", "permissionId": "PERM_ID"}' \
  --json '{"role": "reader"}'

# Update the Sheets row to REMEDIATED
gws sheets +append --spreadsheet-id AUDIT_SHEET_ID --range 'Remediation Log' \
  --values '["2026-03-10","FILE_ID","Revoked anyone-with-link","REMEDIATED","auto-executed after approval"]'