🔐 Security

Introduction

Security is a top priority in Semaphore UI. Whether you're automating critical infrastructure tasks or managing team access to sensitive systems, Semaphore UI is designed to provide robust, secure operations out of the box. This section outlines how Semaphore handles security and what you should consider when deploying it in production.

Authentication & authorization

Semaphore supports secure authentication and flexible authorization mechanisms:

Login methods:
- Username/password
  Default method using credentials stored in the Semaphore database. Passwords are hashed using a strong algorithm (bcrypt).
- LDAP
  Allows integration with enterprise directory services. Supports user/group filtering and secure connections via LDAPS.
- OpenID Connect (OIDC)
  Enables single sign-on with identity providers like Google, Azure AD, or Keycloak. Supports custom claims and group mappings.
Two-Factor authentication (2FA)
TOTP-based 2FA is available and recommended for all users.
Role-based access control
You can assign different roles to users such as Admin, Maintainer, or Viewer, limiting access based on responsibility.
Session management
Sessions are protected with secure HTTP cookies. Session expiration and logout mechanisms ensure minimal exposure.

Secrets & credentials

Managing secrets securely is a core feature:

Encrypted key store
Credentials and secret variables are encrypted at rest using AES encryption.
Environment isolation
Secrets are only passed to jobs at runtime and are not exposed to the container environment directly.
SSH keys and tokens
Users are responsible for uploading valid SSH keys and tokens. These are encrypted and only used when running tasks.

Running untrusted code / playbooks

Semaphore runs user-defined playbooks and commands, which can be risky:

Container isolation
Tasks are executed in isolated Docker containers. These containers have no access to the host system.
Least privilege
Containers run with minimal permissions and can be restricted further using Docker flags.
Chroot execution
Semaphore can execute tasks inside a chroot jail to further isolate the execution environment from the host system.
Task process user
Tasks can be executed under a dedicated non-root system user (e.g., semaphore) to reduce the impact of potential exploits. This is optional and can be configured based on system policies.

Secure Deployment

To ensure Semaphore is securely deployed:

Use HTTPS
Semaphore supports HTTPS both via its built-in TLS support and through a reverse proxy like Nginx. It is strongly recommended to enable HTTPS in production.

To enable built-in HTTPS support add following block to config.json:
```
{
    ...
    "tls": {
        "enabled": true,
        "cert_file": "/path/to/cert/example.com.cert",
        "key_file": "/path/to/key/example.com.key"
    }
    ...
}
```
Run behind a firewall
Limit access to the Semaphore UI and database to only trusted IPs.
Database security
Use strong passwords and restrict database access to Semaphore only.

Updates & patch management

Security updates are published regularly:

Stay updated
Always use the latest stable release.
Changelog
Review changes on GitHub before updating.
Automatic updates
If using Docker, consider automation pipelines for regular updates.

Reporting Vulnerabilities

Found a vulnerability? Help us keep Semaphore secure:

Responsible disclosure
Please email us at [email protected].
No public exploits
Do not share vulnerabilities publicly until patched.
Acknowledgments
Security researchers may be acknowledged in release notes if desired.