# BreachWatch Commands

## Overview

BreachWatch is a powerful, secure add-on feature that monitors the internet and dark web for breached accounts matching records stored within your Keeper Vault. BreachWatch delivers the most in-depth monitoring available to the public with a database of over a billion records while upholding Keeper's state-of-the-art, zero-knowledge security architecture. More details can be found [here](https://docs.keeper.io/enterprise-guide/breachwatch).

## User Experience

To sign up for BreachWatch from Keeper's Web Vault or mobile app, navigate to the BreachWatch screen and follow the on-screen prompts. You can also purchase BreachWatch directly from the [Keeper Security website](https://keepersecurity.com/checkout). After signup, BreachWatch performs a local scan of passwords that are currently stored in your Keeper vault.

BreachWatch Supports 4 Commands in SDK.

1. [BreachWatch List](#breachwatch-list)
2. [BreachWatch Scan](#breachwatch-scan)
3. [BreachWatch Password](#breachwatch-password)
4. [BreachWatch Ignore](#breachwatch-ignore)

### BreachWatch List

The `breachwatch list` command **lists Keeper Vault records and their associated password breach status** as detected by the **BreachWatch** service. It helps identify **weak, reused, or breached passwords** in your vault.

<details>

<summary>DotNet CLI</summary>

**Command:** `breachwatch list`

**Flags:**

* **— numbered**: This flag displays breachwatch records in a serial numbered order
* **— owned**: This flag displays breachwatch records which belong to the owner
* **— all:** This flag displays breachwatch record which the current user has access to. There can be both owned records and records which are shared to user which have a different owner.

**Example:**

```sh
My Vault> breachwatch list --numbered --owned
S.No  Record UID              Title                      Description        
----  ----------------------  -------------------------  -------------------
2     record_uid              DemoRecordForWeakPassword  qsaSF@ASFD.CA      
1     record_uid              breachwatchIgnoreTest3     qwdferq@qwef.afqcew
3     record_uid              DemoBreachWatchRecord      
```

</details>

<details>

<summary>DotNet SDK</summary>

**Function:** `BreachWatchRecords()`

The below call can be made provided that vault is initiated and synced.

**Example:**

```csharp
var records = vault.BreachWatchRecords()
.Where(x => x.Status == BWStatus.Weak || x.Status == BWStatus.Breached)
.Where(x => !BreachWatchIgnore.IsRecordIgnored(vault, x.RecordUid)) 
.Select(x => x)
```

</details>

<details>

<summary>PowerCommander</summary>

**Command:** `Get-KeeperBreachWatchList`

**Flags:**

```
OwnedOnly - Shows records from breachwatch belonging to user
All - Shows all records from breachwatch which user has access to
Numbered - Shows serial number in result
```

**Example:**

```
PS> Get-KeeperBreachWatchList -OwnedOnly -Numbered

S.No Record UID             Title                     Description
---- ----------             -----                     -----------
   1 record_uid             breachwatchIgnoreTest3    qwdferq@qwef.afqcew
 
```

**Command**: `Get-KeeperIgnoredBreachWatchRecords`

**Example:**

```
PS > Get-KeeperIgnoredBreachWatchRecords

Record UID             Title Description                        Status
----------             ----- -----------                        ------
2lAzF6Ok4xAfA-DYd6LQVQ Test1 a@gmail.com (at) https://agoda.com Ignored

Total ignored records: 1
```

</details>

<details>

<summary>Python CLI</summary>

**Command**: `breachwatch list`

**Options**:

* `-n` `--numbered` Displayed records as a numbered list
* `-a` `--all` Display all breached records (default - first 30 records)
* `-o` `--owned` Display only breached records owned by user

**Example:**

```sh
My Vault> breachwatch list

Detected High-Risk Password(s)

Record UID              Title                       Description
----------------------  --------------------------  ----------------
record_uid              hello new shortcut changed  test@example.com
```

</details>

<details>

<summary>Python SDK</summary>

**Function:** `breach_watch_records`

```python
record_uids = {x.record_uid for x in context.vault.vault_data.breach_watch_records() if x.status in (client_pb2.BWStatus.WEAK, client_pb2.BWStatus.BREACHED)}
records = [x for x in context.vault.vault_data.records() if x.record_uid in record_uids and (x.flags & vault_record.RecordFlags.IsOwner if owned_only else True)]
```

</details>

### BreachWatch Scan

The `breachwatch scan` command is used to **submit newly created or updated passwords in your vault for BreachWatch scanning**. This scan detects whether the password is **reused**, **weak**, or **compromised.**

Use it **after creating or modifying records** with passwords, especially if they were added outside of Keeper apps (e.g., via: Commander CLI, API scripts etc).

<details>

<summary>DotNet CLI</summary>

**Command:** `breachwatch scan`

**Example:**

```sh
My Vault> breachwatch scan           
No records found to scan or all eligible records have already been scanned.
```

</details>

<details>

<summary>DotNet SDK</summary>

**Function:** `ScanAndStoreRecordStatusAsync`

This function requires **record Uids** as a list of string

**Example:**

```csharp
await vault.ScanAndStoreRecordStatusAsync(recordUids);
```

</details>

<details>

<summary>PowerCommander</summary>

**Command:** Not Supported

</details>

<details>

<summary>Python CLI</summary>

**Command**: `breachwatch scan`

**Parameters**:

* `-r` `--records` Record UIDs to be scanned

**Example:**

```sh
My Vault> breachwatch scan -r <record_uid>
Breachwatch: 1 password(s) to scan
Scan completed for record <record_uid>. Status: WEAK
```

</details>

<details>

<summary>Python SDK</summary>

**Function:** `scan_and_store_record_status`

```python
bw_password = vault.breach_watch_plugin().scan_and_store_record_status(
                record_uid=record_uid,
                record_key=record_key,
                password=password
            )
            ##fetch the record key and password of the record to be scanned
```

</details>

### BreachWatch Password

`breachWatch password` is a Keeper security feature that continuously monitors your stored vault passwords for exposure in public data breaches. It analyses passwords using zero-knowledge encryption to determine if they are Safe or not.

<details>

<summary>DotNet CLI</summary>

**Command:** `breachwatch password`

**Example:**

```sh
My Vault> breachwatch password 
Password to Check: *************
Scanning 1 password(s)...
   *************: GOOD
```

</details>

<details>

<summary>DotNet SDK</summary>

**Function:** `ScanPasswordsAsync`\
**Example:**

```csharp
public static async Task<List<(string Password, HashStatus Status)>> ScanPasswordsAsync(
            IEnumerable<(string Password, byte[] Euid)> passwordEntries,
            CancellationToken cancellationToken = default)
```

</details>

<details>

<summary>PowerCommander</summary>

Checks one or more passwords against the BreachWatch database to see if they were exposed in known data breaches.

**Command:** Test-PasswordAgainstBreachWatchAlias: kbwp

**Syntax**

```
Test-PasswordAgainstBreachWatch [-Passwords <SecureString[]>] [-ShowPassword] [-VaultContextVar <string>] [<CommonParameters>]
```

**Parameters**

<table data-header-hidden><thead><tr><th width="196.759765625">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>-Passwords</code></td><td>One or more passwords (as SecureString) to check. Accepts pipeline input. If omitted, you are prompted to enter a password.</td></tr><tr><td><code>-ShowPassword</code></td><td>Show the actual password in the results instead of masking it.</td></tr><tr><td><code>-VaultContextVar</code></td><td>Variable path where the vault context is stored. For advanced usage when using a non-default vault context.</td></tr></tbody></table>

**Examples on how this can be used:**

{% code overflow="wrap" %}

```ps1
# Prompt for a password and check it
PS> Test-PasswordAgainstBreachWatch

# Check a specific password
PS> $pwd = ConvertTo-SecureString "password123" -AsPlainText -Force
PS> Test-PasswordAgainstBreachWatch -Passwords $pwd

# Check multiple passwords and show them in results
PS> $pwd1 = ConvertTo-SecureString "pass1" -AsPlainText -Force
PS> $pwd2 = ConvertTo-SecureString "pass2" -AsPlainText -Force
PS> Test-PasswordAgainstBreachWatch -Passwords $pwd1,$pwd2 -ShowPassword

# Pipeline input
PS> Get-KeeperRecord | ForEach-Object { $_.GetPassword() } | ConvertTo-SecureString -AsPlainText -Force | Test-PasswordAgainstBreachWatch
```

{% endcode %}

**Example:**

```powershell
PS> Test-PasswordAgainstBreachWatch
Password to Check: ************
Scanning 1 password(s)...
Processing 1 result(s)...
    ************: WEAK | Strength: System.Object[] (Score: 0)
```

</details>

<details>

<summary>Python CLI</summary>

**Command:** `breachwatch password`

**Parameters:**

* `passwords` Input passwords to be scanned

**Example:**

```sh
My Vault> breachwatch password testpassword
    testpassword: BREACHED
```

</details>

<details>

<summary>Python SDK</summary>

**Function:** `scan_passwords`

```python
breach_watch = vault.breach_watch_plugin().breach_watch.scan_passwords(passwords)
##Pass a list of password strings to be scanned
```

</details>

### BreachWatch Ignore

`breachWatch ignore` is a feature that allows users to **suppress alerts or warnings** for specific password records that have been flagged as weak, reused, or breached by Keeper's BreachWatch service.

This is useful when a user or admin acknowledges a password issue but decides **not to take immediate action** — for example, when a record is:

* Used for legacy systems
* Not critical or already protected by other means
* Already being remediated

<details>

<summary>DotNet CLI</summary>

**Command**: `breachwatch ignore`

**Example:**

```sh
My Vault> breachwatch ignore record_uid            
Record (UID: record_uid) has been ignored.
```

</details>

<details>

<summary>DotNet SDK</summary>

**Function:** `IgnoreRecord`

**Example:**

```csharp
await BreachWatchIgnore.IgnoreRecord(vault, recordUid);
```

</details>

<details>

<summary>PowerCommander</summary>

**Command**: `Set-KeeperBreachWatchRecordIgnore`

```powershell
PS> Set-KeeperBreachWatchRecordIgnore -RecordUids record_uid                            
System.Threading.Tasks.VoidTaskResult
Record 'breachwatchIgnoreTest3' (UID: record_uid) has been ignored.
```

</details>

<details>

<summary>Python CLI</summary>

**Command:** `breachwatch ignore`

**Parameters:**

* `records` Record UIDs of records to be removed from breachwatch

**Example:**

```sh
My Vault> breachwatch ignore record_uid
record_uid: success 
Syncing...
```

</details>

<details>

<summary>Python SDK</summary>

**Function:** Not Supported

</details>