Before you install: creating DBSheriff's database users

DBSheriff connects to every database it monitors with its own service accounts — never your application's credentials, never a shared admin login. This page is the at-a-glance summary across all twelve engines: what accounts DBSheriff needs, what each is for, and whether the grant is straightforward SQL or something else (a cloud IAM role, a service principal, a key pair). For the exact CREATE USER/GRANT statements, follow the link to that engine's own setup guide — this page tells you what to expect before you get there, not the copy-paste commands.

How to start the scripts

The commands on this page and in the engine guides are written as python3 scripts/<name>.py ..., the form for a source checkout or a package that carries the scripts/ folder. On a host installed with install.sh the same four tools (setup_dbsheriff, create_reset_dbuser, install_prereqs, onboard_target) run from the DBSheriff image, so there is no scripts/ folder to find and nothing to install on the host:

sudo /opt/dbsheriff/current/deploy/onprem/stack.sh tool setup_dbsheriff postgresql db1.acme.internal
sudo /opt/dbsheriff/current/deploy/onprem/stack.sh tool create_reset_dbuser mysql prod-mysql.rds.amazonaws.com --dry-run

Everything after the tool name is the command line shown in this guide. The tool uses your terminal (it asks questions), runs as the user who ran sudo, not as root, and writes any file it produces (a credentials file, a generated password) to the directory you ran it from, so run it from a directory of yours: it refuses /, and refuses, where it can tell, a directory the user behind sudo cannot write to (sudo -i starts in /root, which that user cannot enter) before it starts anything. It reaches the Admin Console at http://admin-console:8502 on the stack's own network, and a database your DBSheriff host can reach is reached from the container the same way.

One command for all of it: setup_dbsheriff.py

python3 scripts/setup_dbsheriff.py postgresql db1.acme.internal
python3 scripts/setup_dbsheriff.py hana hana-01.acme.internal
python3 scripts/setup_dbsheriff.py snowflake myorg-myaccount
python3 scripts/setup_dbsheriff.py mongodb mongo1.acme.internal
python3 scripts/setup_dbsheriff.py redshift mycluster.abc123.us-east-1.redshift.amazonaws.com

The engine is one of postgresql, mysql, oracle, mssql, hana, snowflake, mongodb, redshift (use mssql, not sqlserver, for SQL Server).

Covers PostgreSQL, MySQL, Oracle, SQL Server, SAP HANA, Snowflake, MongoDB (self-managed and Atlas both) and Redshift. Checks/enables the server prerequisites and creates all five DBSheriff roles in one run, behind a single "proceed? [y/N]" — --roles=monitor,kill to create fewer than all five, --optional-prereqs=pgaudit to also enable an engine's recommended-but-not-required extras (pgaudit for PostgreSQL, the DBSHERIFF_AUTH audit policy for HANA, Snowflake's network policy, and so on — each engine's setup guide names its own; MongoDB's profiling prerequisite is required, so it's already included by default, and --optional-prereqs=profile_size adds the recommended system.profile size), --dry-run to preview. It never restarts the database server under any circumstance; if a restart is still needed when it finishes, it tells you the exact command and stops there. It's a thin wrapper over the two scripts below — same logic, same tests — for when you'd rather run one command than two.

Automate it: create_reset_dbuser.py

For nine of the twelve engines below, you don't have to run any of this by hand at all. scripts/create_reset_dbuser.py connects to the target as your database admin, creates or resets any of the accounts below with the exact grants its setup guide documents, and (if the server is already registered in the Admin Console) updates the stored credential for you:

python3 scripts/create_reset_dbuser.py postgresql db1.acme.internal
python3 scripts/create_reset_dbuser.py mysql prod-mysql.rds.amazonaws.com --dry-run
python3 scripts/create_reset_dbuser.py postgresql prod.rds.amazonaws.com --ca-file rds-global-bundle.pem

It asks which platform the target runs on (self-managed, AWS, GCP, Azure), whether you're creating a new account or resetting an existing one, and which account types to provision. --dry-run prints every statement it would run without touching anything. Snowflake and MongoDB are partially automated (Snowflake generates a key pair instead of asking for a password, signs in as your ACCOUNTADMIN by password, key pair, single sign-on or password with a second factor, asks which databases DBSheriff may read and checks the new key works before it finishes: the Snowflake setup guide lists the options; MongoDB Atlas's lock account needs a manual one-time step the tool explains when you hit it). Databricks, BigQuery, and Cloud Spanner have no SQL/password concept at all — the tool tells you so and points at the setup guide.

Connecting securely, and where the new passwords go

The administrator password and every new account's password cross the scripts' connection to the target, so all four scripts (setup_dbsheriff.py, create_reset_dbuser.py, install_prereqs.py, onboard_target.py) verify the server's certificate by default (--ssl-mode verify-full):

• --ca-file <bundle> names the CA that signed the server's certificate (Amazon RDS / Aurora: the RDS CA bundle for your region; Amazon Redshift, a cluster or a serverless workgroup: amazon-trust-ca-bundle.crt, https://s3.amazonaws.com/redshift-downloads/amazon-trust-ca-bundle.crt; a private or self-signed server: its CA or its own certificate). Without it the system trust store is used.
• A target whose certificate cannot be verified stops the run with a message that names the flag. --ssl-mode require encrypts without verifying (an explicit opt-down that prints a warning); --ssl-mode disable --allow-plaintext sends everything in clear text, for a trusted private link only. Oracle and self-managed MongoDB connect without TLS in the engine's default configuration: enable TLS on the listener, or use the plaintext flag over a private link.
• A generated password is never printed. It goes into the registry (encrypted) when the server is registered, and otherwise into a new file with mode 600 (--credentials-file, default ./dbsheriff-credentials-<server>-<time>.txt) whose path is shown: move it into your password manager and delete the file.
• onboard_target.py reads an RDS instance's or Redshift cluster's AWS-managed master secret only when you pass --use-master-secret; otherwise it asks for a database administrator login.
• MySQL: the accounts' host part is by default the address the script itself connects from (read from the administrator connection), which is the address DBSheriff connects from only when the script runs on the DBSheriff host; otherwise pass --client-host with the address DBSheriff connects from (onboard_target.py asks for it). When that address cannot be read the scripts stop and ask for --client-host, never creating an account for '%'.
• MySQL: the classify account holds one server-level grant, SELECT on performance_schema.threads (and on no other performance_schema table), so that DBSheriff's classification sessions can recognise their own thread; it shows that login the server's live process list. A server set up before this grant existed gets it when the reset of dbsheriff_classify is run (a reset repeats this one grant and no other server-level privilege). A server that has no such table to grant on (MariaDB) skips it with a note.
• Account names must match [A-Za-z][A-Za-z0-9_]*; every database, schema or warehouse name the scripts discover is quoted as an identifier before it goes into a statement.
• On PostgreSQL, MySQL and Redshift a sixth account, plan, is created by default by setup_dbsheriff.py (pass --roles to leave it out) and is included in create_reset_dbuser.py's "all" choice: SELECT on the schemas and nothing else, the login DBSheriff's EXPLAIN of a captured statement can run under. onboard_target.py creates it only when --roles names it (for example --roles=monitor,kill,lock,posture,classify,plan).

Automate the step before that: install_prereqs.py

Before creating any accounts, the target server itself needs certain settings in place (PostgreSQL's pg_stat_statements extension, HANA's global_auditing_state parameter, Snowflake's network policy, MongoDB's profiling command, Redshift's enable_user_activity_logging parameter, and so on) — covers PostgreSQL, MySQL, Oracle, SQL Server, SAP HANA, Snowflake, MongoDB and Redshift:

python3 scripts/install_prereqs.py postgresql db1.acme.internal
python3 scripts/install_prereqs.py hana hana-01.acme.internal
python3 scripts/install_prereqs.py snowflake myorg-myaccount
python3 scripts/install_prereqs.py mongodb mongo1.acme.internal
python3 scripts/install_prereqs.py redshift mycluster.abc123.us-east-1.redshift.amazonaws.com

The engine names are the same as for setup_dbsheriff.py above (mssql, not sqlserver).

It checks what's already in place and, for whatever isn't, asks apply this now? [y/N] before running anything. It never restarts (or, for Redshift, reboots) the database server itself — some of these settings only take effect after a restart, and the script always tells you that up front and points at the exact restart command for your platform, so you restart on your own schedule and re-run it afterward. On a managed platform it detects which settings aren't reachable over a database connection at all (Redshift's parameter isn't readable over SQL at all, even for the master user) and prints the exact cloud CLI command from the setup guide instead of guessing. HANA needs no restart at all for either of its two prerequisites — both apply live. Snowflake needs no restart at all either — its one prerequisite applies live, and it asks for the DBSheriff host's own public IP instead of a platform choice (it's SaaS-only, nothing to choose). MongoDB also needs no restart at all — neither of its two prerequisites (profiling, and the recommended system.profile size) needs one, and it asks which database you're registering instead of a platform-specific cloud identifier (identical question and command on self-managed and Atlas).

The account types, in general

Across every engine that supports the full set, DBSheriff uses up to five accounts, each scoped to exactly what its job needs:

Each engine's setup guide ends with a table of what each account can do if its password leaks: the lock account is data-access-equivalent on Oracle, SQL Server, MySQL, PostgreSQL and Snowflake (it can re-password or take over the accounts it locks), so create it only if you use the lock response.

Not every engine keeps all five separate — some combine kill+lock, some fold posture into monitor by convention, and a few have no SQL concept of "account" at all and use cloud IAM instead. The table below is exact per engine.

Engine by engine

What to do with the credentials once they exist

Whichever way you create them — by hand from the setup guide, or via create_reset_dbuser.py — the username and password (or key) for each account is what you'll enter when you register the server in the Admin Console's Monitored Servers tab. That's the only place these credentials get stored (encrypted at rest); nothing needs to go in a config file or environment variable. See first login quick start for that step.

Questions, or something in this guide doesn't match what you see: SECURITY.md in your release package, or support@dbsheriff.ai.