Skip to content

Commit da7f452

Browse files
author
Corentin Mors
authored
Add integrations documentation (#256)
Add 3 documentations for VSCode, GitHub Action and SIEM.
1 parent 06671cc commit da7f452

13 files changed

+353
-64
lines changed

‎documentation/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,6 @@
77
"nextra-theme-docs": "^2.13.4",
88
"react": "^18.3.1",
99
"react-dom": "^18.3.1",
10-
"sharp": "^0.33.3"
10+
"sharp": "^0.33.4"
1111
}
1212
}

‎documentation/pages/_meta.json

+3-1
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,9 @@
3030
"---3": {
3131
"type": "separator"
3232
},
33-
"logout": "Logout",
33+
"integrations": {
34+
"title": "Integrations"
35+
},
3436
"---4": {
3537
"type": "separator"
3638
},

‎documentation/pages/index.mdx

+4-3
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,14 @@ import { Card, Cards } from 'nextra-theme-docs';
1010

1111
![Dashlane CLI](../public/main.png)
1212

13-
Dashlane CLI is a command line interface for Dashlane. It allows you to interact with your Dashlane account, and to manage your passwords, secure notes, secrets and personal data.
13+
**Dashlane CLI is a command line interface for Dashlane.** It allows you to interact with your Dashlane account, and to manage your passwords, secure notes, secrets and personal data.
1414

15-
Dashlane CLI also allows you to access team admin related features such as accessing your team's member list, Dark Web Insights reports and activity logs.
15+
Dashlane CLI also allows you to access team admin related features such as accessing your team's member list, Dark Web Insights reports and audit logs.
1616

17-
This documentation is separated in two parts:
17+
This documentation is separated in three parts:
1818

1919
<Cards>
2020
<Card title="👤 Personal Commands" href="/personal" />
2121
<Card title="👔 Business Commands" href="/business" />
22+
<Card title="🧩 Integrations" href="/integrations" />
2223
</Cards>

‎documentation/pages/integrations.mdx

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
import { Card, Cards } from 'nextra/components';
2+
3+
# Integrations
4+
5+
We support several integrations with popular services and tools.
6+
Explore the integrations below to learn how to improve your development workflows.
7+
8+
<Cards>
9+
<Card title="🐙 GitHub Action" href="/integrations/github-action" />
10+
<Card title="💻 VS Code Extension" href="/integrations/vscode" />
11+
<Card title="🗂️ Logs to SIEM" href="/integrations/siem" />
12+
</Cards>

‎documentation/pages/integrations/_meta.json

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"github-action": "GitHub Action",
3+
"vscode": "Visual Studio Code",
4+
"siem": "SIEM"
5+
}

‎documentation/pages/integrations/github-action.mdx

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
import { Steps } from 'nextra/components';
2+
3+
# GitHub Action for Dashlane
4+
5+
This CI/CD GitHub Action allows developers to inject their secrets vault from Dashlane to their GitHub workflow.
6+
7+
<Steps>
8+
### Register your device locally
9+
10+
```sh
11+
dcli devices register "action-name"
12+
```
13+
14+
For more details refer to Dashlane CLI documentation https://dashlane.github.io/dashlane-cli
15+
16+
### Set GitHub Action environment secrets
17+
18+
Set the environment variable prompted by the previous step in your GitHub repository's secrets and variables.
19+
20+
![Github Secrets](https://github.com/Dashlane/load-secrets-action/blob/main/documentation/github_secrets.png?raw=true)
21+
22+
### Create a job to load your secrets
23+
24+
Set the same env variables in your pipeline as well as the ids of the secrets you want to read from Dashlane starting with `dl://`.
25+
26+
```yml
27+
steps:
28+
- uses: actions/checkout@v2
29+
- name: Load secrets
30+
id: load_secrets
31+
uses: ./ # Dashlane/github-action@<version>
32+
env:
33+
ACTION_SECRET_PASSWORD: dl://918E3113-CA48-4642-8FAF-CE832BDED6BE/password
34+
ACTION_SECRET_NOTE: dl://918E3113-CA48-4642-8FAF-CE832BDED6BE/note
35+
DASHLANE_SERVICE_DEVICE_KEYS: ${{ secrets.DASHLANE_SERVICE_DEVICE_KEYS }}
36+
```
37+
38+
### Retrieve your secrets in the next steps
39+
40+
Get your secrets in any next step of your pipeline using `GITHUB_OUTPUT`.
41+
42+
```yml
43+
- name: test secret values
44+
env:
45+
ACTION_SECRET_PASSWORD: ${{ steps.load_secrets.outputs.ACTION_SECRET_PASSWORD }}
46+
ACTION_SECRET_NOTE: ${{ steps.load_secrets.outputs.ACTION_SECRET_NOTE }}
47+
```
48+
49+
</Steps>

‎documentation/pages/integrations/siem.mdx

+205
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Send your audit logs to a SIEM
2+
3+
**Read full documentation on how to use the Dashlane CLI to send your audit logs to a SIEM, here: https://github.com/Dashlane/dashlane-audit-logs**
4+
5+
---
6+
7+
This projects allows you to retrieve your Dashlane's audit log and send them in the SIEM or storage solution of your choice, using FluentBit. At the moment, we provide out of the box configurations for the following solutions:
8+
9+
- Azure log analytics workspace
10+
- Azure blob storage
11+
- Splunk
12+
- Elasticsearch
13+
14+
This list is not restrictive, as others destination can be used. You can find the list of supported platforms on FluentBit's website: https://docs.fluentbit.io/manual/pipeline/outputs
15+
16+
## Prerequisites
17+
18+
In order to manage the Dashlane audit logs of your business account, you need to generate the credentials that will be used to pull the logs. The procedure can be found here: https://dashlane.github.io/dashlane-cli/business
19+
20+
## How does it work ?
21+
22+
The Docker image provided leverages the Dashlane CLI tool that will pull the audit logs and send them in your SIEM of choice. By default, when running the image in a container, the logs from DAY-1 will be retrieved, and new logs will be pulled every thirty minutes. To handle the logs, we included FluentBit with this basic configuration file:
23+
24+
```
25+
[INPUT]
26+
Name stdin
27+
Tag dashlane
28+
29+
[OUTPUT]
30+
Name stdout
31+
Match *
32+
Format json_lines
33+
```
34+
35+
To send the logs to a new destination, you need to enrich this configuration file template and add an **OUTPUT** section such as described on the following sections. To use your custom configuration file, you need to override the **DASHLANE_CLI_FLUENTBIT_CONF** environment variable and set the path of your configuration file. The method to pass your file will depend on the plaform you use to run the image.
36+
37+
## Accessing the logs
38+
39+
The first step to retrieve the audits logs is to run the custom image we provide and that can be found here: https://hub.docker.com/r/dashlane/audit-logs
40+
41+
This image can run on the platform of your choice. To make a simple test, you can deploy it with Docker by doing so:
42+
43+
### Environment variables
44+
45+
`DASHLANE_CLI_FLUENTBIT_CONF`
46+
47+
- Path of the FluentBit configuration file
48+
- Default to `/opt/fluent-bit.conf`
49+
50+
`DASHLANE_CLI_RUN_DELAY`
51+
52+
- Delay between each log pull
53+
- Default to `60` seconds
54+
55+
`DASHLANE_TEAM_DEVICE_KEYS`
56+
57+
- Secret key to authenticate against Dashlane servers as the team
58+
- [Documentation to generate the credentials](https://dashlane.github.io/dashlane-cli/business)
59+
60+
### Running in Docker
61+
62+
```
63+
docker pull dashlane/audit-logs
64+
docker run -e DASHLANE_TEAM_DEVICE_KEYS=XXX -it dashlane/audit-logs:latest
65+
```
66+
67+
Running those commands will create a simple container that pull your business every minutes and and print them on the stdout of the container.
68+
69+
### Kubernetes
70+
71+
A helm chart is provided by the repository to deploy the service on Kubernetes.
72+
73+
```bash
74+
helm install dashlane-audit-logs dashlane-audit-logs/
75+
```
76+
77+
Some example of configuration is provided in `example/`.
78+
79+
## SIEM configuration
80+
81+
### Azure Log analytics workspace
82+
83+
To send your Dashlane audit logs on Azure in a Log Analytics Workspace, you can use the template provided in the dashlane-audit-logs repository. The template will create a container instance that will automatically pull and run the Dashlane Docker image and send the logs in a **ContainerInstanceLog_CL** table in the Log Analytics Workspace of your choice. Before deploying the template you will have to provide:
84+
85+
- The location where you want your container to run (ex: "West Europe")
86+
- Your Dashlane credentials
87+
- Your Log Analytics Workspace ID and Shared Key
88+
89+
> **Click on the button to start the deployment**
90+
>
91+
> [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FDashlane%2Fdashlane-audit-logs%2Fmain%2FAzureTemplates%2FLog%20Analytics%20Workspace%2Fazuredeploy.json)
92+
93+
### Azure blob storage
94+
95+
If you want to send your logs to an Azure storage account, you can use the deployment template we provide in the dashlane-audit-logs repository, which will:
96+
97+
- Create a storage account and a file share to upload a custom FluentBit configuration file
98+
- Create a container instance running the Docker image with your custom file
99+
100+
You will need:
101+
102+
- Your Dashlane credentials
103+
- A custom FluentBit configuration file
104+
105+
> **Click on the button to start the deployment**
106+
>
107+
> [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FDashlane%2Fdashlane-audit-logs%2Fmain%2FAzureTemplates%2FBlob%20storage%2Fazuredeploy.json)
108+
109+
Once your container is deployed, copy the following configuration into a file called "fluent-bit.conf".
110+
111+
```
112+
[INPUT]
113+
Name stdin
114+
Tag dashlane
115+
116+
[OUTPUT]
117+
Name stdout
118+
Match *
119+
Format json_lines
120+
121+
[OUTPUT]
122+
name azure_blob
123+
match *
124+
account_name ${STORAGE_ACCOUNT_NAME}
125+
shared_key ${ACCESS_KEY}
126+
container_name audit-logs
127+
auto_create_container on
128+
tls on
129+
blob_type blockblob
130+
```
131+
132+
Then upload in the storage account you just created. In the Azure Portal, go to **Storage accounts**, select the one you just created, go to **File shares**, select **fluentbit-configuration** and upload your configuration file.
133+
134+
> The "blob_type" configuration specifies to create a blob for every log entry on the storage account, which facilitates the logs manipulation for eventual post-processing treatment.
135+
136+
> The configuration provided above is meant to be working out of the box, but can be customized to suit your needs. You can refer to FluentBit's documentation to see all available options: https://docs.fluentbit.io/manual/pipeline/outputs/azure_blob
137+
138+
## Splunk
139+
140+
If you want to send your logs to Splunk, you need to create a HEC (HTTP Event Collector) on your Splunk instance. As an example, we will show here how to create one on a Splunk Cloud instance.
141+
142+
1- On the Splunk console, go to **"Settings / Data input"** and click on **Add New** in the **HTTP Event Collector** line.
143+
144+
2- Give your collector a name and click **Next**
145+
146+
3- In the **Input settings** tab keep the option as is and click on **Next**
147+
148+
4- In the **Review tab**, click on **Submit**. You should see a page indicating that the collector has been created.
149+
150+
> The token provided will be used to authenticate and send the logs to your Splunk instance.
151+
152+
You can make a test by running the following command:
153+
154+
```
155+
curl -k https://$SPLUNK_URL.com:8088/services/collector/event -H "Authorization: Splunk $SPLUNK_TOKEN" -d '{"event": "Dashlane test"}'
156+
```
157+
158+
If all is working you should receive the following response:
159+
160+
```
161+
{"text":"Success","code":0}
162+
```
163+
164+
Finally, to send your Dashlane logs to Splunk, you need to customize your FluentBit configuration file by adding the relevant Splunk configuration:
165+
166+
```
167+
[OUTPUT]
168+
Name splunk
169+
Match *
170+
Host splunk-instance.com
171+
Port 8088
172+
TLS On
173+
splunk_token ${SPLUNK_TOKEN}
174+
```
175+
176+
Here, you just need to change the host parameter and indicate yours, and pass your Splunk token as an environment variable to the container.
177+
Once the data are sent, you can query them by going to the **"Apps/Search and reporting"** menu in the console and type this basic query in the search bar:
178+
179+
```
180+
index=* sourcetype=*
181+
```
182+
183+
You should now be able to access your Dashlane audit logs.
184+
185+
## Elasticsearch
186+
187+
Work in progress
188+
189+
Output configuration for Elasticsearch
190+
191+
```
192+
[OUTPUT]
193+
Name es
194+
Match *
195+
Host host
196+
Port 443
197+
tls on
198+
HTTP_User user
199+
HTTP_Passwd pwd
200+
Suppress_Type_Name On
201+
```
202+
203+
## Notes
204+
205+
All configuration are provided as is and designed to work out of the box. If you want customize them, you can consult the FluentBit documentation: https://docs.fluentbit.io/manual/pipeline/outputs

‎documentation/pages/integrations/vscode.mdx

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# VS Code Extension for Dashlane
2+
3+
The Dashlane VS Code extension helps integrate your favorite IDE with the Dashlane password manager.
4+
5+
You can download it from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Dashlane.dashlane-vscode).
6+
7+
## Features
8+
9+
![Dashlane VS Code extension quick view](https://github.com/Dashlane/dashlane-vscode/blob/main/images/dashlane-vscode-example.png?raw=true)
10+
11+
## Extension Settings
12+
13+
This extension contributes the following settings:
14+
15+
- `dashlane-vscode.shell`: The shell path or a login-shell to override Dashlane CLI process default shell (see Node child_process.spawn()) for more detail.
16+
- `dashlane-vscode.cli`: The path to the Dashlane-CLI binary (resolvable from `$PATH`).

‎documentation/pages/personal/index.mdx ‎documentation/pages/personal.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import { Card, Cards } from 'nextra-theme-docs';
44

55
Accessing your personal vault allows you to view your passwords, secure notes and OTP codes.
66

7-
![Dashlane CLI examples](../../public/cli-examples.png)
7+
![Dashlane CLI examples](../public/cli-examples.png)
88

99
<Cards>
1010
<Card title="🔑 Authentication" href="/personal/authentication" />

‎documentation/pages/personal/_meta.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
{
2-
"index": "Get Started",
32
"authentication": "Authentication",
43
"devices": "Managing your Devices",
54
"vault": "Accessing your Vault",
65
"secrets": "Load secrets",
7-
"backup": "Backup your local Vault"
6+
"backup": "Backup your local Vault",
7+
"logout": "Logout"
88
}

‎documentation/pages/personal/authentication.mdx

-1
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,6 @@ The CLI will open a new **incognito** tab to authenticate you to your SSO provid
3333

3434
- Email code validation (default)
3535
- TOTP code validation (via an authenticator app)
36-
- Dashlane Authenticator push notification
3736
- DUO push notification
3837

3938
By completing the device registration process, you'll be now asked to enter your Master Password.

‎documentation/pages/logout.mdx ‎documentation/pages/personal/logout.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,6 @@ If you want to start fresh with the CLI or use another account, you can logout a
88
dcli logout
99
```
1010

11-
<Callout type="info">This does not perform an account reset, it only resets the local data on the device.</Callout>
11+
<Callout type="info">This action only resets the local data on the device.</Callout>
1212

1313
A confirmation will be asked, then the local database containing your encrypted data will be wiped and any entry related to the CLI will be removed from the OS keychain.

0 commit comments

Comments
 (0)