Access to a Jupyter server is access to run arbitrary code as the user who started it, so an exposed notebook server is a remote shell with the data scientist's cloud credentials attached. Jupyter is now everywhere AI and data work happens: laptops, GPU hosts, JupyterHub clusters, managed notebook services and model development environments. Attackers scan for exposed servers to mine cryptocurrency and harvest cloud keys from the file system. This guide covers how authentication and authorisation work in Jupyter Server and JupyterHub, admin roles, the tokens and credentials notebooks accumulate, logging and detection, and a hardening baseline. It is for platform and MLOps engineers, security teams supporting data science, and anyone running notebooks on shared or cloud infrastructure. Behaviour was checked against the Jupyter Server and JupyterHub documentation and source on GitHub on 27 October 2026.
This is an independent guide from NHI Mgmt Group, based on Project Jupyter's public documentation as of November 2026. It is not sponsored or reviewed by Project Jupyter. Product features change, so confirm settings against Project Jupyter's current documentation.
Key takeaways
- Kernels and terminals are equal to everything. The Jupyter Server documentation states that execute access to kernels or terminals generally means arbitrary code execution and should be considered equivalent to all other permissions. Disabling terminals alone does not make a server safer.
- Never run with an empty token and password. Token authentication is on by default; setting
tokenandpasswordto empty strings disables it and is explicitly not recommended unless another layer authenticates every request. - Bind to localhost and tunnel. The default listen address is
localhost. Most exposures come from changing it to0.0.0.0on a cloud VM with a permissive security group. - The notebook host is a credential store. Cloud credential files, Git tokens, kubeconfigs, database passwords and LLM API keys sit in home directories, environment variables and notebook cells. Attackers who reach an exposed server go straight for them.
- JupyterHub isolates users only with care. JupyterHub is designed for semi-trusted users; for untrusted users you need per-user subdomains, locked-down environments and scoped API tokens.
How identity and access work in Jupyter Server
A single-user Jupyter Server (the backend for JupyterLab and Notebook 7) authenticates requests with a token or password, then optionally authorises them. There is no concept of multiple users in a single-user server: anyone who authenticates is the owner.
| Mechanism | How it works | Security note |
|---|---|---|
| Token (default) | A random token generated at startup, accepted in an Authorization: token ... header, a ?token= URL parameter or the login form | Printed to the terminal and shown by jupyter server list; URLs with tokens end up in shell history, chat and browser history |
| Password | jupyter server password stores an argon2 hash in jupyter_server_config.json | When a password is set, token authentication is not enabled by default; use TLS so the password is not sent in clear |
| Session cookie | Set after first login, so the token is not needed again in that browser | Cookie theft equals session theft |
| Custom IdentityProvider | A class (jupyter_server.auth.IdentityProvider) that identifies the user, for example from a proxy or JupyterHub | Used by JupyterHub's single-user servers to accept Hub-issued OAuth tokens |
| No authentication | c.ServerApp.token = "" and c.ServerApp.password = "" | Not recommended; only safe if an authenticating proxy is the sole path to the port |
Authorisation
Authorisation is off by default: every authenticated request is allowed. Operators can set ServerApp.authorizer_class to a class whose is_authorized(handler, user, action, resource) method returns true or false. Requests are labelled read (GET, HEAD), write (POST, PUT, PATCH, DELETE) or execute (kernel and terminal WebSockets).
| Resource | Read | Write | Execute |
|---|---|---|---|
contents (/api/contents, /files) | Read files | Create, modify, delete files | None |
kernels (/api/kernels) | List kernels | Start, stop, restart | Send code to the kernel: arbitrary code execution |
terminals (/api/terminals) | List terminals | Start and stop terminals | Shell access: arbitrary code execution |
sessions | List sessions | Create and delete sessions, including starting kernels | None |
nbconvert | Render notebooks; depending on configuration this could involve execution | None | None |
server (/api/shutdown) | None | Shut the server down | None |
A useful read-only role is therefore possible, for example letting reviewers read contents but denying all write and execute actions, but anyone with execute on kernels can do everything else by other means.
Notebook document trust
Opening a notebook someone else wrote should not run code. Jupyter signs notebooks whose outputs the current user produced, storing signatures in nbsignatures.db (for example ~/.local/share/jupyter/nbsignatures.db on Linux). Untrusted HTML is sanitised and untrusted JavaScript is never run; HTML and JavaScript in Markdown cells are never trusted. Executing a cell is always trusted, so a malicious notebook is only dangerous once someone runs it: review code from shared repositories before executing.
Admin roles and privileged access
On a single-user server the operating system account is the privilege boundary. In JupyterHub, roles and scopes control who can manage other users' servers.
| Role or setting | What it grants | Guidance |
|---|---|---|
| OS account running the server | Everything the kernel and terminal can do: files, network, credentials in that home directory | A dedicated unprivileged account; allow_root defaults to False, keep it |
JupyterHub admin role | All scopes, full rights to all actions; cannot be edited | Few named users via c.Authenticator.admin_users; admins can access other users' servers if configured |
JupyterHub user role | Scope self: the user's own resources | Default for everyone |
JupyterHub token role | Scope inherit: the same permissions as the token's owner | Request narrower scopes when creating tokens |
JupyterHub server role | Post activity for itself only | Leave as is |
| JupyterHub services | No default role, so no access to guarded endpoints | Grant each service a custom role with only the scopes it needs |
Custom roles (for example servers scope) | Start and stop specific users' or groups' servers | Use for teaching assistants or operators instead of admin |
- Semi-trusted by design: the JupyterHub security overview says the Hub is not suitable for untrusted users in its default configuration, because the Hub and all single-user servers share one domain behind the proxy, so browser cross-origin protections do not separate them.
- Isolation requirements: users must not be able to modify their own single-user server environment: no installing packages into the environment that runs
jupyterhub-singleuser, no changingPATHorPYTHONPATH, no editing~/.jupyter, and no unrestricted choice of container image. - Subdomains: per-user subdomains are, in the documentation's words, the only reliable way to isolate user servers from each other. Server sharing is off by default; do not enable it for untrusted users without subdomains.
Integrations, API tokens and service accounts
Notebooks are where people paste credentials to "just get it working". Treat every notebook host as a place where non-human identity credentials accumulate.
| Credential | Where it usually sits | Better pattern |
|---|---|---|
| Jupyter server token | Terminal output, jupyter server list, URLs in history and chat | Password or Hub OAuth; never share token URLs; restart to rotate |
| JupyterHub API tokens | Users' scripts, services' config | Scoped tokens with expiry; services with custom roles |
| Cloud access keys | ~/.aws/credentials, gcloud config, Azure CLI cache, environment variables | Instance or workload identity (IAM role, service account, managed identity) with short-lived tokens |
| Git and package tokens | ~/.git-credentials, .netrc, pip and conda config | Fine-grained, read-only, expiring tokens; credential helpers |
| Database and warehouse passwords | Hard-coded in cells or .env files | Fetched at run time from a secrets manager |
| LLM and AI API keys | Cells, environment variables, .env | Gateway with per-user keys and spend limits; never in saved notebooks |
| Kubeconfigs | ~/.kube/config on GPU or cluster hosts | Short-lived OIDC credentials; no cluster-admin from notebooks |
- Outputs persist secrets: a cell that prints a token saves it in the
.ipynbJSON. Clear outputs before committing and run secret scanning on notebook repositories. See the Git Secret Scanning Guide. - Managed notebook platforms: notebook features embedded in cloud services carry the platform's own credentials. In ChaosDB, a chain of misconfigurations in the Jupyter Notebook feature of Azure Cosmos DB let a researcher reach other customers' primary read-write keys and notebook authentication tokens.
- Workload identity: give notebook hosts a role scoped to the datasets and buckets they need, not an engineer's personal keys. See the AI Infrastructure Workload Identity Guide.
Logging and detection
Jupyter Server logs through Python logging, configured with ServerApp.logging_config (a dictConfig object), and can write to a file as well as stderr. It scrubs sensitive URL parameters by default (token, auth, key, code, state, xsrf); add your own with extra_log_scrub_param_keys. Server logs show requests, kernel starts and terminal sessions, but not what code ran, so host telemetry matters more.
| Signal | Source | Why it matters |
|---|---|---|
| Terminal sessions opened from unknown addresses | Jupyter Server log, proxy log | The built-in terminal gives an interactive shell on the host |
Shell, curl or wget spawned by the Jupyter or kernel process | EDR or auditd process events | Payload download (T1105 Ingress Tool Transfer) |
| Reads of cloud credential files by kernel processes | File access auditing, canary credentials | Credential harvesting (T1552.001 Credentials In Files) |
Changes to cron, authorized_keys, sshd_config, /etc/ld.so.preload | File integrity monitoring | Persistence (T1053.003 Cron, T1098.004 SSH Authorized Keys) |
| Unexpected kernel module loads | Host telemetry | Rootkits such as Diamorphine (T1014 Rootkit) |
| Sustained CPU or GPU use with outbound connections to mining pools, Telegram or Discord APIs | Cloud monitoring, egress logs | Cryptomining (T1496.001 Compute Hijacking) and exfiltration |
| Truncated auth or cron logs | Log pipeline gaps | Anti-forensics |
| JupyterHub admin actions and token creation | Hub logs | New admin, new long-lived token |
See the Cryptojacking Guide and, if credentials were exposed, the Cloud Credential Compromise Playbook.
Metrics
- Exposure: Jupyter servers reachable from the internet, found by external scans (target 0).
- Unauthenticated servers: servers with empty token and password, found by configuration scanning (target 0).
- Static cloud keys on notebook hosts: count of credential files found by host scanning (target 0, replaced by workload identity).
- Secrets in notebooks: secret scanning findings in
.ipynbfiles per month, trending down. - Hub admins: users with the admin role, reviewed quarterly.
Hardening baseline
- Inventory: find every notebook server: developer laptops, cloud VMs, GPU hosts, Kubernetes notebooks, managed services. Look for listening ports such as 8888 and for
jupyterprocesses in host inventories. - Network: keep
ServerApp.ipatlocalhostand reach remote servers over an SSH tunnel, VPN or authenticating proxy. Leaveallow_remote_accessat its default so Host header checks protect against DNS rebinding, and do not setallow_originto*. - Authentication: keep token authentication or set a password; for teams use JupyterHub with SSO. Never set both token and password empty, and keep
disable_check_xsrfFalse. - TLS: terminate TLS at a proxy or set
certfileandkeyfile, so tokens, passwords and cookies are not sent in clear. - Least privilege on the host: run as an unprivileged account, keep
allow_rootFalse, run in a container with a read-only base image where possible, and restrict egress to package mirrors and data sources. - Kernel transport: on shared hosts, set
KernelManager.transport_encryptiontoautoorrequiredso ZMQ kernel sockets use CurveZMQ (requires a libsodium-enabled pyzmq and kernels that declare support), since by default any local process that can reach those ports can read kernel messages. - Authorisation and unauthenticated endpoints: where reviewers need access, add an
Authorizerrather than sharing tokens; reviewallow_unauthenticated_access, which defaults to True in Jupyter Server 2.x for endpoints without an authentication rule, and test extensions before setting it False. - JupyterHub: enable per-user subdomains for untrusted or mixed users, lock user environments, give services custom roles, and keep admins few.
- Secrets: move credentials to workload identity and a secrets manager, add canary credentials to notebook hosts, and scan notebook repositories.
- Patch and roll back: pin Jupyter Server, JupyterLab and extension versions in an environment file, test upgrades on a staging image, and keep the previous image for rollback.
Laptop, team server or platform
- Individual laptop: defaults are reasonable: localhost binding and a token. The main risks are copying token URLs into chat and keeping long-lived cloud keys in the home directory.
- Shared team VM: do not run one shared server with one token for a team; it gives everyone the same identity and no audit trail. Use JupyterHub or per-user servers.
- Enterprise platform: JupyterHub or a managed notebook service with SSO, per-user containers, workload identity, egress control and central logging. Treat it as a production system with change control.
Common misconfigurations
- Bound to 0.0.0.0 on a cloud VM with an open security group "to share with a colleague", often with authentication disabled for convenience. Internet scanners find these quickly.
- Token URLs shared in chat or tickets: the token is a full credential until the server restarts.
- Running as root in a container with the host's Docker socket or cloud metadata reachable, turning notebook access into host or cloud compromise.
- Personal cloud admin keys on the GPU host: one compromised notebook becomes a cloud account takeover. See the LLMjacking Guide for how stolen AI keys are abused.
- JupyterHub on one domain with untrusted users and sharing enabled, letting one user serve HTML or JavaScript that acts in another user's session.
- Secrets saved in outputs and pushed to Git with the notebook.
Framework mapping
| Control area | NIST SP 800-53 Rev 5 | NIST CSF 2.0 | CIS Controls v8.1 | ISO/IEC 27001:2022 Annex A |
|---|---|---|---|---|
| Authentication and authorisation | IA-2, AC-3, AC-6 | PR.AA-05 | 6.3, 6.8 | A.5.15, A.8.5 |
| Network exposure and TLS | SC-7, SC-8, CM-7 | PR.PS-01 | 4.4, 12.2 | A.8.20, A.8.24 |
| Credentials on notebook hosts | IA-5 | PR.AA-01 | 3.11, 5.2 | A.5.17 |
| Monitoring and logging | AU-12, SI-4 | DE.CM-09 | 8.2, 13.1 | A.8.15, A.8.16 |
Practitioner checklist
- Scan for internet-reachable Jupyter servers and close every one.
- Confirm no server runs with an empty token and password, and that
disable_check_xsrfis False. - Keep
ServerApp.ipon localhost and use SSH tunnels, VPN or an authenticating proxy for remote access. - Serve over TLS and run as an unprivileged user with
allow_rootFalse. - Replace static cloud keys on notebook hosts with workload identity and add canary credentials.
- Scan notebook repositories for secrets in code and saved outputs.
- For JupyterHub, keep admins few, give services custom roles, scope tokens and enable subdomains for untrusted users.
- Monitor terminal sessions, child processes of kernels, persistence file changes and mining or messaging egress.
- Enable CurveZMQ kernel transport encryption on shared hosts where supported.
- Pin and patch Jupyter components with a tested rollback image.
Standards and references
- Jupyter Server: Security in the Jupyter Server
- Jupyter Server: Running a public Jupyter Server
- Jupyter Server: Configuring Logging
- JupyterHub: Security Overview
- JupyterHub: Roles
- MITRE ATT&CK: T1496.001 Compute Hijacking
Related NHI Mgmt Group resources: Self-Hosted LLM Security Guide · Cryptojacking Guide · AI Infrastructure Workload Identity Guide · Honeytokens and Canary Credentials Guide