Securing the Salt Master: Keys, Network, Access Control, salt-api and Patching

SaltStack 28 min min read Updated: Nov 17, 2026 Advanced
Securing the Salt Master: Keys, Network, Access Control, salt-api and Patching
Advanced Topic 1 of 2

Why the Master Matters

The Salt master can run commands as root on every minion. If an attacker controls the master, they control the fleet. Salt has had serious security fixes in the past, including remote code execution problems. So you treat the master like a domain controller: small, patched, restricted and watched.

Patch quickly: Keep the master and minions on a supported Salt release and apply security updates fast. Subscribe to the Salt Project security announcements and check the release notes for CVE fixes before each upgrade.

Step 1: Limit the Network

PortUseWho should reach it
4505/tcpPublish (master sends commands)Only minion networks
4506/tcpRequest/return (minions send results, request files and pillar)Only minion networks
8000/tcp (or your choice)salt-apiOnly admin tools and CI systems, behind TLS or a proxy
22/tcpSSH to the masterOnly admin or bastion networks
bash # UFW example (Ubuntu): allow minion network only sudo ufw default deny incoming sudo ufw allow from 10.20.0.0/16 to any port 4505 proto tcp sudo ufw allow from 10.20.0.0/16 to any port 4506 proto tcp sudo ufw allow from 10.0.5.0/24 to any port 22 proto tcp sudo ufw enable # firewalld example (RHEL family) sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="10.20.0.0/16" port port="4505" protocol="tcp" accept' sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="10.20.0.0/16" port port="4506" protocol="tcp" accept' sudo firewall-cmd --reload
Minions connect out: Minions open the connection to the master. You do not open any inbound port on minions. This is a big security advantage of the default ZeroMQ design.

Step 2: Control Key Acceptance

  • Keep auto_accept: False (the default). Never set it to True on a master that can be reached from untrusted networks
  • Check the fingerprint of the minion key before you accept it
  • Use salt-key -a only for known ids. Use salt-key -L often to look for unexpected pending keys
  • Consider pre-seeded keys or a controlled reactor with extra checks for cloud servers
  • Reject or delete keys for retired servers
bash # On the minion: show its fingerprint sudo salt-call --local key.finger # On the master: compare with the pending key sudo salt-key -f web-9 sudo salt-key -a web-9 # Optional: put the master fingerprint in the minion config so the minion checks the master sudo salt-key -F master # on the master # minion config: # master_finger: 'ab:cd:...'

Step 3: Run the Master With Least Privilege

yaml # /etc/salt/master.d/security.conf user: salt # the packages usually create this user. Check your install # Files under /etc/salt, /var/cache/salt, /var/log/salt and /srv should be owned correctly: # sudo chown -R salt:salt /etc/salt /var/cache/salt /var/log/salt /var/run/salt # chmod 700 /etc/salt/pki/master # chmod 640 /etc/salt/master /etc/salt/master.d/*
Check your package defaults: Current packages may already run the master as the salt user. Read the install guide for your version and test after any change. The minion normally runs as root, because it manages the system.
ItemSetting
Private keys/etc/salt/pki/master/master.pem must be mode 400 or 600 and owned by the master user
Pillar filesReadable only by the master user. Pillar can hold secrets
LogsDo not log secrets. Avoid -l debug in production for long periods
ConfigNot world-writable. Keep in Git, deployed by a trusted process

Step 4: Give People Limited Access (eauth and ACLs)

By default only root on the master can run salt. To let other users run some commands on some targets, use external authentication (eauth) with external_auth for the salt command and salt-api, or the simpler publisher_acl for local users.

yaml # /etc/salt/master.d/acl.conf # Local Linux users allowed to use the salt command, with limits publisher_acl: deploy: - 'web*': - test.ping - service.restart - state.apply monitoring: - '*': - test.ping - status.* - disk.usage # External auth: PAM users or groups, for CLI (-a pam) or salt-api external_auth: pam: alice: - .* # full access: use only for real admins ops%: # group ops (the % means group) - '@runner': - jobs.list_jobs - manage.up - 'web*': - test.ping - service.* ci-bot: - 'web*': - state.apply: kwargs: mods: app.deploy
bash # Use eauth from the CLI salt -a pam 'web*' test.ping # prompts for a PAM user and password salt-run -a pam jobs.list_jobs
ACL rule idea: Give each person or bot the smallest list of targets and functions. A CI bot that only runs state.apply app.deploy on web* cannot do much damage if its password leaks.

Step 5: Secure salt-api

salt-api offers a REST interface to Salt, usually through the rest_cherrypy module. It is powerful, so protect it.

yaml # /etc/salt/master.d/api.conf rest_cherrypy: port: 8000 host: 127.0.0.1 # bind locally and put nginx with TLS in front, or use TLS here ssl_crt: /etc/pki/tls/certs/salt-api.crt ssl_key: /etc/pki/tls/private/salt-api.key disable_ssl: False max_request_body_size: 1048576
bash sudo systemctl enable --now salt-api # Login returns a token, then use it TOKEN=$(curl -sk https://localhost:8000/login -H 'Accept: application/json' \ -d username=ci-bot -d password="$PASS" -d eauth=pam | jq -r '.return[0].token') curl -sk https://localhost:8000/ -H "X-Auth-Token: $TOKEN" -H 'Accept: application/json' \ -d client=local -d tgt='web*' -d fun=test.ping
  • Always use TLS. Never send passwords over plain HTTP
  • Limit access by IP in the firewall or the reverse proxy
  • Use short token lifetimes (token_expire) and a dedicated bot user for each system
  • Log API access. Rate limit at the proxy
  • Do not expose salt-api to the internet

Step 6: Watch and Record

  • Keep the master log and job cache (keep_jobs_seconds) long enough to investigate. Send job returns to a central place with a returner or an event forwarder
  • Review salt/auth and salt/key events for unexpected keys
  • Use salt-run jobs.list_jobs to see who ran what (the User field)
  • Use operating system auditd rules on /etc/salt and /srv
  • Alert when salt-key -L shows unknown pending keys
yaml # master config: send all job returns to an external system too master_job_cache: local_cache # default; switch to a returner-based cache if you need event_return: syslog # send events to syslog event_return_whitelist: - salt/auth - salt/key - salt/job/*/new

Step 7: Protect Secrets

  • Use encrypted pillar, Vault or an SDB backend (see the secrets lesson). Do not commit secrets to plain Git
  • Keep pillar targeting strict: a minion should only get the pillar it needs
  • Give gitfs deploy keys read-only access
  • Restrict who can edit states: a state is code that runs as root on minions

Security Checklist

CheckDone?
Salt master and minions are on a supported, patched version
Ports 4505, 4506 limited to minion networks
auto_accept is off. Fingerprints are verified
Master runs as a non-root user with correct file modes
Users and bots use publisher_acl or external_auth with minimal rights
salt-api uses TLS, is firewalled, and uses short tokens
Secrets are encrypted or in Vault, not in plain pillar in Git
Changes to states go through code review
Events and jobs are logged and monitored
Backups of the master key and config exist and are protected

Practice Tasks

  1. Write firewall rules that allow only a minion network to ports 4505 and 4506
  2. Give a deploy user permission to run only state.apply on web* and test it
  3. Compare publisher_acl and external_auth
  4. Set up salt-api with TLS and call test.ping with a token
  5. List five signs of a compromised master that you would monitor

Conclusion

Treat the master like your most sensitive server. Limit the network, never auto-accept keys, run with least privilege, give users narrow ACLs, secure salt-api with TLS, protect secrets, log everything and patch quickly.

Quick Summary: ports 4505/4506 restricted; no auto_accept; fingerprints; non-root user; publisher_acl/external_auth; salt-api TLS; patch CVEs.

Get Newsletter

Subscibe to our newsletter and we will notify you about the newest updates on Edugators