Vaults and credentials

Vaults keep the user names and passwords your tasks sign in with: passwords are encrypted, never shown to anyone, and handed to an agent only while it runs a task that needs them.

#Vaults and credentials

• A vault groups credentials, for example Production or Test systems.
• A credential lives in a vault and has a Name, a Username, a Password and a Description. Tasks refer to it by vault name and credential name.

Open Vaults to see the vaults you can use. Select a vault on the left to list its credentials with their username and the time they were last updated. The password column always shows dots.

#Create vaults and credentials

Only administrators create and change vaults and credentials.

1. Click New vault, enter a name and a description, and save.
2. Select the vault and click New credential.
3. Enter the Name (tasks use it; quotes and backticks are not allowed), the Username, the Password and an optional Description, then click Create.

To change a credential, open its menu and choose Edit or replace password. Leave Password empty to keep the stored one. The vault's own menu offers Rename or describe and Delete vault.

Warning: Deleting a vault deletes all its credentials. Deleting a credential, or renaming it or its vault, makes the tasks that use it fail until you update them.

#Who can use a vault

To grant access, select the vault and click Access (Manage vaults only). In the Access to vault drawer, click Add role or user, choose a role or a user and keep Use ticked, then click Save. An empty list means only users with Manage vaults or Use every vault can use the vault. A user with several roles can use the vaults granted to any of them.

A grant always means use: tasks started by that role or user may read the vault's credentials. Nobody but an administrator can add, change or delete credentials, and nobody can view a stored password.

#Use a credential in a task

Read a credential into a variable with set --type:credential, then use its Username and Password properties:

set --name:erp --type:credential --vault:"Production" --credential:"ERP Bot"
browser --action:open --url:"https://erp.example.com/login" --output:web
capture --browser:$web$ --action:settext --dompath:"//input[@id='user']" --value:$erp.Username$
capture --browser:$web$ --action:settext --dompath:"//input[@id='password']" --value:$erp.Password$
capture --browser:$web$ --action:click --dompath:"//button[@type='submit']"

In the properties panel, the vault and credential fields offer pickers with the vaults and credentials you can use.

Tip: On the Vaults page, the copy button next to a credential copies the matching set --type:credential line to the clipboard.

Commands that take a credential variable, such as mail, accept it directly, for example --credential:$mailbox$.

#Email accounts

The mail command asks for its account itself: choose the vault and the credential in the properties panel (they are shown with the required fields), and it signs in with that credential's user name and password. There is no separate set line, and the password never appears in the task:

mail --action:send --smtp:"smtp.gmail.com" --port:587 --vault:"Mail" --credential:"Robot mailbox" --from:"robot@company.com" --to:"team@company.com" --subject:"Report" --body:"The report is attached" --attachment:"C:\Reports\daily.pdf"
mail --action:read --server:"imap.gmail.com" --vault:"Mail" --credential:"Robot mailbox" --subject:"Invoice" --output:messages

Store the mail address (or the account's user name) as the credential's user name. Gmail, Outlook.com and Yahoo do not accept the normal password from programs: turn on 2-step verification for the account and store an app password instead. Microsoft 365 mailboxes where password sign-in is switched off use --authtype:oauth2 with an app registration; see mail. A relay server that takes mail without signing in needs no credential (--authtype:none).

If the server refuses the sign-in, the error says so and the command is not repeated by --retry, because repeated failures can lock the account.

#Looping over e-mails

To handle e-mails one by one, use a loop of the type mail (Loop · Mail in the command palette, or type "email loop" in Ctrl+K). It takes the same account, folder and filters as mail --action:read — vault and credential pickers, server suggestions, unread, from, to, subject, text, since, before, with attachments, at most — and runs its commands once per matching message, newest first. The loop variable is the current message, a record with Id, From, FromName, To, Cc, Subject, Date, Body, HtmlBody, IsRead and Attachments (the variable picker offers them as $msg.Subject$ and so on). Inside, pass --id:$msg.Id$ to the mail actions that work on one message:

loop --type:mail --server:"imap.gmail.com" --vault:"Mail" --credential:"Robot mailbox" --unread:true --subject:"Invoice" --hasattachments:true --variable:msg --index:i
    log --message:"$i$: $msg.Subject$ from $msg.FromName$"
    mail --action:saveattachments --server:"imap.gmail.com" --vault:"Mail" --credential:"Robot mailbox" --id:$msg.Id$ --destination:"C:\Invoices" --filter:"*.pdf"
    mail --action:move --server:"imap.gmail.com" --vault:"Mail" --credential:"Robot mailbox" --id:$msg.Id$ --target:"Processed"
endloop

• The messages are read once, when the loop starts (at most --max, 50 by default); messages that arrive while the loop runs wait for the next run.
• --markread:true marks all the messages read as soon as they are read, before the first round. To mark a message read only after it was handled, leave --markread off and end the round with mail --action:markread --id:$msg.Id$: a message whose round fails then stays unread and is picked up again by the next run.
• When the account, folder or filters are wrong, the error points at the loop's line, as do the log lines and the debugger (a breakpoint on the loop stops there twice: before the messages are read and before the first round).
• Any agent that can run mail --action:read runs the loop; only --index needs the current agent.

#When the password is read

The agent asks the server for the credential when the set --type:credential command runs. The server hands it over only if:

• the agent is running that execution and the execution is running, and
• the user who started the run may use the vault. For a scheduled run, that is the user who created the schedule.

Otherwise the command fails with a message such as The user who started the execution has no access to vault 'Production'.

#CyberArk

If your organization keeps its passwords in CyberArk, create a CyberArk vault: its credentials store no password, only where CyberArk finds the account. Each time a task reads such a credential, the Botream server fetches the password from the CyberArk Central Credential Provider (CCP, the AIMWebService REST API) and hands it to the agent running the task, exactly like a Botream credential. Agents never connect to CyberArk, and Botream does not cache CyberArk passwords: every read asks CyberArk again, so a rotated password is used right away.

Tasks do not change: set --type:credential --vault:"CyberArk ERP" --credential:"ERP Bot" and the vault and credential fields of mail work the same for both vault types, and access grants work the same too.

#What to set up in CyberArk

Ask your CyberArk administrator for:

1. An application (Applications in the PVWA), for example Botream. Its Application ID is what Botream sends.
2. Application authentication for it:
   • Allowed machines: the address of the Botream server (not the agents: only the server calls CyberArk).
   • Certificate authentication (recommended): a client certificate issued to the Botream server, given to you as a PFX (.pfx/.p12) file with its private key and password. Other methods (OS user, path, hash) do not apply, because Botream calls the web service over the network.
3. Safe permissions: the application and the Credential Provider user of the CCP (usually Prov_<server>) must be members of each safe Botream reads, with Retrieve accounts (and List accounts to use queries).
4. The address of the Central Credential Provider web service, for example https://ccp.company.local. If the web service requires client certificates (IIS Require SSL and client certificates), the PFX above is the one to use.

#Create a CyberArk vault

1. Click New vault, choose CyberArk under Where the passwords are kept, and enter a name.
2. Central Credential Provider address: the base address, such as https://ccp.company.local. Botream adds /AIMWebService/api/Accounts.
3. Application ID: as set in CyberArk.
4. Client certificate: click Upload certificate, choose the PFX file and enter its password. After saving, the form shows only the certificate's subject and expiry date (for example Installed: CN=botream-server · expires 10/12/2027); the file and its password are never shown again. Use Replace certificate or Remove to change it.
5. Verify the TLS certificate stays on. If the provider's certificate comes from an internal CA, paste that CA's certificate (PEM) into CA certificate or click Load from file (.pem, .crt or .cer). Turn verification off only for a test system.
6. Timeout (seconds) (default 30) limits how long Botream waits for an answer. Vault connection timeout is CCP's ConnectionTimeout (how long the provider waits for the CyberArk Vault); leave it empty for the provider's default.
7. Under Test connection, enter a Safe and an Object (account name) the application may read and click Test connection. On success you see OK: CyberArk returned the account of user svc_rpa; the password is never shown.

The vault list shows a CyberArk tag next to CyberArk vaults. A vault's type can be changed only while it has no credentials.

#Add a CyberArk credential

Select the CyberArk vault, click New credential and enter:

• Name: the name tasks use.
• How CyberArk finds the account: Safe and object (the Safe, the Object — the account's name in CyberArk — and optionally the Folder, default Root), or Query in CCP query syntax, for example Safe=RPA;UserName=svc_rpa.
• Username (optional): leave empty to use the user name CyberArk returns; fill it in to always use this one.

Click Test to fetch the account: the result shows OK with the user name, never the password. The credential list shows where each account is in CyberArk instead of the password dots.

#When CyberArk refuses

The server calls GET {address}/AIMWebService/api/Accounts?AppID=…&Safe=…&Folder=…&Object=… (or &Query=…) with the client certificate, and a Reason such as Botream execution 1234 that appears in CyberArk's audit. If CyberArk does not return the password, the set command (or the mail command) fails with a message saying why, and the test buttons show the same:

#Security

• The connection settings, including the client certificate and its password, are stored encrypted (AES-256-GCM) like Botream passwords, and only the certificate's subject and expiry are ever shown.
• CyberArk passwords are not stored in Botream and are not cached; they exist on the server only while being handed to the agent.
• Every read is audited (Credential access with the provider, or Credential access failed with the reason), and so is every test (Vault connection test, Credential test) — never with a password.
• The agent masks CyberArk passwords in logs like any other credential.

#How passwords are protected

• Encrypted at rest with AES-256-GCM. The key is set on the server at installation; back it up with the server, because stored passwords cannot be read without it. See Upgrade and backup.
• Never shown: no page and no API returns a password, not even to administrators. A password can only be replaced.
• Masked in logs: the agent replaces every password it has read with *** in log lines, error messages, the error variable of a catch and task outputs. The variables shown in failure details and in the debugger are masked too.
• Sent only while running: agents receive a password only during the run that asks for it.

Note: Use HTTPS between the server, browsers and agents in production, so credentials never cross the network in plain text. See Install the server.

#Audit

Every vault and credential change, every grant change and every attempt to read a credential is recorded in the audit log, without the password: