gogcli Drive 审计命令实战：用 `gog drive tree/du/inventory/audit` 做只读的清理规划与权限排查

gogcli Drive 审计命令实战用gog drive tree/du/inventory/audit做只读的清理规划与权限排查【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本指南围绕 gogcli 的 Drive 审计Drive Audits命令集展开介绍如何在不修改任何文件的前提下用gog drive tree、gog drive du、gog drive inventory、gog drive audit sharing/user等只读命令完成文件夹结构盘点、容量汇总、库存导出与权限风险排查。读完本文你将掌握这些命令的参数用法、JSON 输出约定、失败语义与批量操作的安全边界可直接用于清理规划、迁移审查和需要稳定 JSON 的自动化场景。Drive 审计命令是什么gogcli 的 Drive 审计命令是一组只读的报告型工具定位是清理规划cleanup planning、迁移审查migration review以及需要稳定 JSON 输出、但不回写 Drive 的自动化任务。与gog drive bulk这类批量变更命令不同审计命令本身不做任何写入核心包括 8 个命令命令用途gog drive tree打印只读的文件夹树gog drive du汇总文件夹大小gog drive inventory导出只读的 Drive 库存清单gog drive audit sharing找出公开或外部共享权限gog drive audit user找出授予某个用户的权限gog drive ls列目录gog drive get获取单个对象元数据gog drive raw获取原始 Drive API 对象适用场景判断当你只是想看文件夹内容、体积或库存而不改动文件时就走这套命令当需要批量改权限、批量移除公开共享时应切换到gog drive bulk系列并配合--dry-run详见下文。输出约定人看表格机器看 JSON所有审计命令都支持统一的输出控制最常用的两个标志是-j/--json/--machine向 stdout 输出 JSON最适合脚本消费-p/--plain/--tsv输出稳定、可解析的纯文本TSV无颜色。其余通用标志还包括--color auto|always|never、--max、--depth、--parent、--all-drives默认true可配合--no-all-drives、--results-onlyJSON 模式下只输出主结果、丢弃nextPageToken等信封字段以及--selectJSON 模式下按逗号分隔选取字段最佳实践是用--fields。这些标志的完整定义可以在对应命令页如 gog-drive-tree中查看。在源码层命令统一通过outfmt.IsJSON(ctx)判断输出格式、用outfmt.WriteJSON写出 JSON非 JSON 时走outfmt.WriteTable见 internal/cmd/drive_reporting.go因此同一套标志在 tree、du、inventory、audit 上的行为一致。文件夹树gog drive tree打印可读的文件夹树gog drive tree --parent folderId --depth 2当结果需要交给其他工具消费时改用 JSONgog drive tree --parent folderId --depth 3 --json关键参数--parent起始文件夹 ID缺省为 root--depth最大深度0表示不限制默认值为 2--max返回的最大条目数0表示不限制默认值为 0即不截断。tree的 JSON 输出包含items与truncated两个字段当扫描因--max被截断时truncated为true并且非 JSON 模式会向 stderr 提示 Results truncated; increase --max to see more.。从源码看tree请求的字段集为driveTreeFieldsid,name,mimeType,size,modifiedTime,shortcutDetails(...)每行输出一个placement见下文多父目录与 placement并附带path与depth信息internal/cmd/drive_reporting.go 中的driveTreeItem结构。大小汇总gog drive du汇总文件夹体积gog drive du --parent folderId --max 20 gog drive du --parent folderId --depth 2 --sort size --jsondu的关键参数与默认值--depth文件夹汇总的深度默认 1--max最多返回的文件夹数默认 500为不限--sort按size、path或files排序默认size--orderasc/desc默认desc。多父目录与 placement 语义drive tree和drive inventory对每个发现的 placement 输出一行——所谓 placement是指文件在某条路径上的一个出现位置。因此通过多个父目录都能到达的历史遗留条目会在每条路径下各自保留一次。而drive du会把这些 placement 独立聚合成文件夹汇总再按size、path或files排序。这套逻辑对应 internal/drivereport 包中的traverse.goplacement 遍历与summary.go聚合汇总du命令本身在 internal/cmd/drive_reporting.go 的DriveDuCmd中实现先调用listDrivePlacements全量扫描不设深度/条目上限若意外截断会直接返回 drive du truncated unexpectedly 错误保证汇总结果完整。快捷方式Shortcut如何处理快捷方式会被计为内容字节为零的文件 placement扫描过程不会跟随 shortcut 指向的目标去递归。也就是说du的容量统计只反映真实文件所占空间避免因 shortcut 造成重复或虚高的体积。库存导出gog drive inventory导出只读的条目清单gog drive inventory --parent folderId --json gog drive inventory --parent folderId --max 0 --depth 0 --json drive-inventory.json当需要一份机器可读的 Drive 对象列表用于审查、diff 或下游清理脚本时使用 inventory 输出。它的关键参数--depth默认 0即默认全深度扫描--max最大条目数默认 500--sort按path、size或modified排序默认path--order默认asc。相比 treeinventory 额外请求了owners(emailAddress,displayName)字段见 internal/cmd/drive_reporting.go 的driveInventoryFields因此每条记录会带出属主邮箱/显示名便于后续按属主归类做清理或迁移评估。把--max 0 --depth 0组合即可一次性导出完整清单重定向到文件。修订历史gog drive revisions先列出某文件的修订元数据再查看某一条修订gog drive revisions list fileId --all --json gog drive revisions get fileId revisionId --jsonDrive API 会暴露修订 ID、时间戳、keep-forever永久保留状态以及可用的 provider 导出链接。需要特别注意的是对于 Google 原生文档Docs/Sheets/Slides 等 Docs Editors 文件API 并不暴露完整的编辑历史或历史文档正文所以这里只能拿到修订元数据无法拿回历史版本内容。revisions list的默认--max为 200可通过--all拉取全部分页或--max/--limit控制--fail-empty可在没有任何修订时以退出码 3 结束便于脚本判断。相关命令页gog-drive-revisions、gog-drive-revisions-list、gog-drive-revisions-get。权限审计gog drive audit sharing与gog drive audit user找出公开或外部共享gog drive audit sharing --parent folderId --internal-domain example.com --json gog drive audit sharing --parent folderId --public-only --fail-foundaudit sharing别名permissions、perms、public、external扫描指定文件夹树对每个条目拉取权限列表并判定是否存在风险共享。关键参数--internal-domain视为内部的域名可重复传多次不指定时默认取当前账号邮箱的域名--public-only只报告 anyone-with-link / 公开权限--external-only只报告外部用户/组/域权限--file / --file-id只审计单个文件 ID而不是整个文件夹树--fail-found存在发现项时以退出码 3结束便于 CI 判定--max最多扫描的文件/文件夹数默认 500--depth最大文件夹深度默认 2。注意--public-only与--external-only不能同时使用源码会直接返回 usage 错误见 internal/cmd/drive_audit.go。一条发现项finding会带出path、mimeType、ownerEmails、permissionId、permissionType、role、email、domain、allowFileDiscovery、deleted、expirationTime、reasons与inherited等字段其中reasons标明命中原因是public还是externalinherited/permissionDetails则记录了权限是否从父级继承而来。判定逻辑internal/cmd/drive_audit.go 中的driveSharingFinding/isExternalDrivePermissiontypeanyone判为 publictypeuser或group时比较邮箱域名、typedomain时比较域若不在--internal-domain名单内则判为 external。内部域名单会做小写化与去首尾点号归一化normalizeDomain并以sortedKeys的形式回显在 JSON 输出的internalDomains字段中。找出共享给特定用户的文件gog drive audit user clawdbotgmail.com --parent folderId --jsonaudit user user接收一个用户邮箱作为位置参数扫描文件夹树后找出所有授予该用户权限的条目。与 sharing 相同也支持--file/--file-id、--parent、--depth、--max、--all-drives、--fail-found。两条 audit 命令的 JSON 输出都包含findings、findingCount、scannedFileCount、truncated以及 sharing 的internalDomains便于脚本统计覆盖率。批量权限操作与审计的边界批量权限操作被刻意与审计命令分开且必须经过 dry-run 或确认才能执行gog drive bulk remove-public --parent folderId --dry-run gog drive bulk update-role --parent folderId --from writer --to reader --target contractorexample.com --dry-run也就是说审计负责发现问题bulk 负责解决问题二者职责分离防止误操作。失败语义分页必须完整绝不输出部分成功审计命令在安全方面有几个刻意设计的行为值得在自动化时重点理解权限分页必须全部完成对扫描范围内的每个文件权限列表的分页都要走完。API 调用失败、出现重复的 page token、或遇到页数限制错误时整个命令会失败并拒绝输出部分审计结果——绝不给出半份的审计报告避免下游依据残缺数据做决策。批量操作先完成权限扫描再写入gog drive bulk系列在执行任何变更之前会先完成上述完整的权限扫描。因此如果列表/扫描阶段失败写入会被阻止a listing failure prevents writes但需要明确这并不能回滚后续写入阶段本身发生的失败。计划类操作请始终先跑--dry-run验证扫描能完整通过。重复 page token 防护文件夹列表遍历同样拒绝重复的 page token。从源码看listDriveChildren每次翻页前都会调用pageTokenGuard检查internal/cmd/drive_reporting.go一旦发现 token 被重复使用即报错终止防止死循环或脏数据。这些报告在产出输出之前就会拒绝这类异常 token而成功完成的扫描会保留其既有的 size 与 depth 上限语义。退出码约定--fail-found审计有发现项时与--fail-emptyrevisions 无结果时均使用退出码 3表达有结论/无结论的脚本可判定状态。共享盘Shared Drives控制审计命令在底层 Drive API 支持的情况下默认包含共享盘。如果需要把扫描范围限制在我的云端硬盘My Drive传入--no-all-drivesgog drive inventory --parent root --no-all-drives --json--all-drives在所有审计类命令上默认值为true且可否定negatable对应源码中AllDrives bool ... default:true negatable:_的定义internal/cmd/drive_reporting.go 与 internal/cmd/drive_audit.go。底层请求会带上supportsAllDrives语义以正确遍历共享盘。对象级检查--fields与原始对象当需要对单个对象做精细检查时用gog drive get配合--fields精确选取需要的字段gog drive get fileId --fields id,name,mimeType,size,owners,emailAddress --json如果连字段裁剪都不需要、要拿 Drive API 的原始对象则用gog drive raw。raw输出的敏感字段处理行为脱敏/标记等详见文档 Raw API Dumps。drive get与drive raw构成审计链路的最后两块拼图前者适合快速字段探查后者适合需要完整原始结构的调试与取证。实战组合建议把上述命令串成一条典型的只读审计流水线# 1) 先出完整库存清单 gog drive inventory --parent folderId --max 0 --depth 0 --json drive-inventory.json # 2) 再按体积看哪里最占空间 gog drive du --parent folderId --depth 2 --sort size --max 20 --json # 3) 排查公开共享风险CI 里可用 --fail-found 触发告警 gog drive audit sharing --parent folderId --public-only --fail-found --json # 4) 确认某个外部协作者拿到的权限范围 gog drive audit user contractorexample.com --parent folderId --json # 5) 确认无误后再进入 bulk 阶段且先 dry-run gog drive bulk remove-public --parent folderId --dry-run整套链路只读、可脚本化、可判定退出码 3既适合人工清理规划也适合定时任务做持续的安全巡检。所有命令的完整标志表可在 docs/commands 目录下对应命令页中查阅实现细节可进一步阅读 internal/cmd/drive_reporting.go、internal/cmd/drive_audit.go 与 internal/drivereport 包。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考