diff --git a/docs/network-policy/integration-policy-examples.mdx b/docs/network-policy/integration-policy-examples.mdx index 7c6866c848e..9d1f0658205 100644 --- a/docs/network-policy/integration-policy-examples.mdx +++ b/docs/network-policy/integration-policy-examples.mdx @@ -4,7 +4,7 @@ title: "Common NemoClaw Integration Policy Examples" sidebar-title: "Integration Policy Examples" description: "Guided examples for adding post-install integration policy access to a NemoClaw sandbox." -description-agent: "Guides users through common post-install integration policy setup for maintained NemoClaw policy presets, including Outlook, messaging channels, GitHub, Jira, Brave and Tavily web search, package managers, Hugging Face, local inference, and OpenShell approval workflows." +description-agent: "Guides users through common post-install integration policy setup for maintained NemoClaw presets and a custom Gmail policy, including Outlook, messaging channels, GitHub, Jira, Brave and Tavily web search, package managers, Hugging Face, local inference, and OpenShell approval workflows." keywords: ["nemoclaw integration policy examples", "post-install policy setup", "openshell approval workflow", "policy preset"] content: type: "how_to" @@ -14,7 +14,8 @@ skill: import { AgentOnly } from "../_components/AgentGuide"; Use these examples when a sandbox is already installed and an integration needs network access. -This page covers only integrations that NemoClaw currently ships as maintained policy preset YAML under `nemoclaw-blueprint/policies/presets/`. +Most examples use maintained policy preset YAML that NemoClaw ships under `nemoclaw-blueprint/policies/presets/`. +The Gmail example shows how to author a custom preset because NemoClaw does not ship a maintained Gmail preset. For complete blueprint examples that combine a model, agent harness, OpenShell policy, and integration workflow, refer to [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community). Integration setup usually has two separate parts: @@ -106,6 +107,129 @@ Keep OAuth client secrets and refresh tokens out of policy files. If the tool still fails, run `openshell term`, trigger the workflow again, and inspect the blocked request. If the blocked endpoint is not covered by the maintained `outlook` preset, treat it as a separate policy review instead of assuming it is part of the supported preset. +## Gmail and Google Workspace Mail + +NemoClaw does not currently ship a maintained `gmail` preset. +Do not reuse the `outlook` preset for Gmail: Microsoft Graph and Gmail use different hosts, authentication flows, and API paths. +First determine whether your tool uses the Gmail REST API, IMAP, or SMTP. +Apply only the custom preset for the protocol your tool uses. + +### Gmail REST API + +The following `gmail-rest.yaml` preset supports listing and reading messages, downloading attachments, sending messages, refreshing an OAuth token, and loading the Gmail discovery document. +It restricts egress to the documented Gmail and OAuth paths and to the Python executable that opens the connection. + +```yaml +preset: + name: gmail-rest + description: "Gmail REST API access for Python mail tools" +network_policies: + gmail-rest: + name: gmail-rest + endpoints: + - host: gmail.googleapis.com + port: 443 + protocol: rest + enforcement: enforce + rules: + - allow: { method: GET, path: "/$discovery/rest" } + - allow: { method: GET, path: "/gmail/v1/users/**/messages" } + - allow: { method: GET, path: "/gmail/v1/users/**/messages/**" } + - allow: { method: POST, path: "/gmail/v1/users/**/messages/send" } + - allow: { method: POST, path: "/upload/gmail/v1/users/**/messages/send" } + - host: oauth2.googleapis.com + port: 443 + protocol: rest + enforcement: enforce + rules: + - allow: { method: POST, path: "/token" } + - host: www.googleapis.com + port: 443 + protocol: rest + enforcement: enforce + rules: + - allow: { method: GET, path: "/discovery/v1/apis/gmail/v1/rest" } + binaries: + - { path: /usr/bin/python3* } +``` + +Preview and apply the REST preset: + +```bash +$$nemoclaw my-assistant policy-add --from-file ./gmail-rest.yaml --dry-run +$$nemoclaw my-assistant policy-add --from-file ./gmail-rest.yaml --yes +``` + +If the TUI reports a different Python executable, replace `/usr/bin/python3*` with that executable instead of adding unrelated binaries. +Add other Gmail methods or paths only when your workflow requires them. + +### Gmail IMAP + +Use IMAP for a Python downloader that connects to `imap.gmail.com`, including a tool that authenticates with an app password and downloads attachments. +Save the following preset as `gmail-imap.yaml`. + +```yaml +preset: + name: gmail-imap + description: "Gmail IMAP access for a Python mail downloader" +network_policies: + gmail-imap: + name: gmail-imap + endpoints: + - host: imap.gmail.com + port: 993 + access: full + tls: skip + binaries: + - { path: /usr/bin/python3* } +``` + +Preview and apply the IMAP preset: + +```bash +$$nemoclaw my-assistant policy-add --from-file ./gmail-imap.yaml --dry-run +$$nemoclaw my-assistant policy-add --from-file ./gmail-imap.yaml --yes +``` + +### Gmail SMTP + +Add SMTP only when the tool sends mail through SMTP instead of the Gmail REST API. +Use `smtp.gmail.com:465` for implicit TLS or `smtp.gmail.com:587` for STARTTLS, but do not authorize both ports unless the tool needs both. +The SMTP entry uses the same L4 shape as the IMAP entry: + +```yaml +preset: + name: gmail-smtp + description: "Gmail SMTP access for a Python mail sender" +network_policies: + gmail-smtp: + name: gmail-smtp + endpoints: + - host: smtp.gmail.com + port: 465 + access: full + tls: skip + binaries: + - { path: /usr/bin/python3* } +``` + +Replace port `465` with `587` when the client uses STARTTLS. +Preview and apply the resulting file: + +```bash +$$nemoclaw my-assistant policy-add --from-file ./gmail-smtp.yaml --dry-run +$$nemoclaw my-assistant policy-add --from-file ./gmail-smtp.yaml --yes +``` + + +Keep OAuth client secrets, refresh tokens, app passwords, and downloaded credential JSON files out of policy YAML. +IMAP and SMTP use opaque L4 tunnels, so OpenShell cannot inspect or restrict their methods, paths, commands, or message contents after the connection is allowed. +Authorize only the host, port, and connection-opening binary that your workflow requires. + + +Run the Gmail workflow with `openshell term` open after applying the selected preset. +Inspect blocked requests and add only endpoints and binaries you can explain. + ## Telegram Bot Messaging Telegram needs channel configuration and egress policy.