Skip to content

Commit

Permalink
Add some clarifications to API client section (#1008)
Browse files Browse the repository at this point in the history
  • Loading branch information
@predictiple
predictiple authored Mar 4, 2025
1 parent ff04566 commit 505bfc7
Show file tree
Hide file tree
Showing 5 changed files with 131 additions and 97 deletions.
138 changes: 88 additions & 50 deletions content/docs/server_automation/server_api/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,10 @@ collections on hosts and retrieve the results of those collections.

## Why an API?

Modern detection and DFIR work consist of many different products and
tools all working together. In reality Velociraptor is just a part of
a larger ecosystem consisting of network detections, SIEM or other
tools. It is therefore important to ensure that Velociraptor
integrates well with other tools.
Modern threat detection and DFIR work consists of many different products and
tools all working together. In reality Velociraptor is just a part of a larger
ecosystem consisting of network detections, SIEM or other tools. It is therefore
important to ensure that Velociraptor integrates well with other tools.

Generally there are two main requirements for Velociraptor integration:

Expand Down Expand Up @@ -85,75 +84,114 @@ server is now listening on all interfaces.
[INFO] 2021-11-07T01:57:26+10:00 Starting gRPC API server on 0.0.0.0:8001
```

### Creating a client API certificate
### Creating an API client configuration

You can create a new client api certificate which allows the client
program to identify itself with the server. The server will verify
that the certificate is signed by the Velociraptor CA prior to
accepting connections. The produced YAML file contains private keys,
public certificates and the CA's certificate.
You can create a new client api config file which includes a client certificate
that allows the client program to identify itself with the server. The server
will verify that the certificate is signed by the Velociraptor CA prior to
accepting connections. The produced YAML file contains private keys, public
certificates, the CA's certificate, and connection parameters.

```sh
velociraptor --config server.config.yaml config api_client --name Mike --role administrator api.config.yaml
Example:
```
$ velociraptor --config server.config.yaml config api_client --name Mike --role administrator api.config.yaml
```

This command can be broken into:
1. `--config server.config.yaml` load the server config which contains
the CA private keys needed to sign a new minted certificate.
2. `config api_client` generate an api_client certificate
3. `--name Mike`: Certificates represent identities. The name of the
certificate will be used to identify the caller and place ACLs on
it.
4. `--role administrator`: This option will also assign a role to the
new certificate name. The role is used to test permissions of what
the caller may do.
1. `--config server.config.yaml`: load the server config which contains
the CA private keys needed to sign a new minted certificate. This also allows
the CLI command to create a new user in the server's datastore.

2. `config api_client`: generate an api_client configuration, including client
certificate.

3. `--name Mike`: Certificates represent user identities. The name of the
certificate will be used to identify the caller and enforce ACLs on it.

4. `--role administrator`: This option will also assign a role to the new
identity. The role is used to test permissions of what the caller may do. If
`--role` is specified then the user will be created on the server if it does
not already exist. In the example above the user is granted the role
`administrator` which includes all the permissions of the minimal API role
`api` - see note below.

The API connection string included in the API config is constructed from the
values `API.hostname` and `API.bindaddress` in the server configuration, so you
should ensure that these are set correctly before generating the API config
file.

#### Managing API roles

The Velociraptor GUI contains a User Management screen where you can inspect all
the currently issued API users as well as GUI users. There is inherently no
difference between API users and GUI users other than the fact that API users
are authenticated with certificates.

![User Management](user_management.png)


##### Granting roles

For an API user to be able to connect it must have at least the `api` role. This
is the minimum role to allow external connections to the API. In addition the
API user will need roles granted that provide it with the permissions that you
need it to have. The roles and permissions should be appropriate for your
specific use case. Note that the `administrator` role is very powerful and we
recommend that external programs NOT be given this role. Instead consider
carefully what permission the external program requires on the server and select
the appropriate role for it based on "least permissions" principles.


You can also change the permission of an existing certificate (or
user) by simply granting a different role.
##### Inspecting roles

At any time you can inspect the roles given to the user using the `acl show`
command.

```
velociraptor --config /etc/velociraptor/server.config.yaml acl grant Mike --role administrator,api
$ velociraptor --config server.config.yaml acl show bob@local
{"roles":["administrator","api"]}
```

{{% notice tip "Granting roles" %}}
Or you can view the roles and effective permissions in the GUI's User Management
screen:

For an API key to be able to connect the key must have the `api` role
as well. This is a minimum role to allow external connections. The
`administrator` role is very powerful and we recommend external
programs not be given this role. Instead think what permission the
external program requires on the server and select the appropriate
role for it.
![User Management > Roles and Permissions](viewing_acls.png)

If a key is compromised you can remove its role using the same
command. This prevents the key from being used on the server at all.
Or you can query the roles using VQL:

```
velociraptor --config /etc/velociraptor/server.config.yaml acl grant Mike --role ""
```vql
SELECT * FROM gui_users() WHERE name = "bob@local"
```

{{% /notice %}}
##### Changing roles

Roles can be easily added or removed in the GUI's User Management screen.

At any time you can inspect the roles given to the key using the `acl
show` command.
On the command line you can change the permissions of an existing
user by granting a different role using the `acl grant` command. The `acl grant`
command _replaces_ the existing roles - it does not add to them.

```
$ velociraptor --config /etc/velociraptor/server.config.yaml acl show Mike
{"roles":["administrator","api"]}
$ velociraptor --config server.config.yaml acl grant Mike --role investigator,api
```

{{% notice tip "Managing API roles" %}}
Note that role role changes made from the CLI require a service restart. You
will see a message recommending this after running the `acl grant` command.
Changes made in the GUI or VQL do not require a service restart.

Since release 0.6.7 the Velociraptor GUI contains a user management
pane. You can use this to inspect all the currently issued API users
as well as GUI users (There is inherently no difference between API
users and GUI users other than the fact that API users are
authenticated with certificates).
##### Removing roles

Ensure the `any query` permission is provided to an API user so they
can connect over the API.
If an API client's credentials are compromised you can remove all its roles
using the `acl grant` command. This prevents the credentials from being used on
the server at all.

```
$ velociraptor --config server.config.yaml acl grant Mike --role ""
```

In the GUI this can be achieved by deselecting all roles from the user in all
orgs.

{{% /notice %}}

## Python bindings

Expand Down
78 changes: 41 additions & 37 deletions content/docs/server_automation/server_api/api_comms.excalidraw
View file
Original file line number Diff line number Diff line change
Expand Up @@ -146,8 +146,8 @@
},
{
"type": "text",
"version": 451,
"versionNonce": 1687471730,
"version": 452,
"versionNonce": 149767276,
"index": "b1k",
"isDeleted": false,
"id": "r3C6jU2iIL6ERmdtkh3t2",
Expand All @@ -157,7 +157,7 @@
"roughness": 1,
"opacity": 100,
"angle": 0,
"x": 782.4853515625,
"x": 781.1572265625,
"y": 160,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
Expand All @@ -168,7 +168,7 @@
"frameId": null,
"roundness": null,
"boundElements": [],
"updated": 1732529040795,
"updated": 1740832028756,
"link": null,
"locked": false,
"fontSize": 20,
Expand Down Expand Up @@ -334,25 +334,25 @@
"width": 299,
"height": 35.14436123081083,
"angle": 0,
"strokeColor": "#1e1e1e",
"strokeColor": "#868e96",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 4,
"strokeStyle": "solid",
"roughness": 1,
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": "b9J",
"roundness": {
"type": 2
},
"seed": 1545384882,
"version": 473,
"versionNonce": 705974510,
"seed": 527615468,
"version": 496,
"versionNonce": 1956707284,
"isDeleted": false,
"boundElements": [],
"updated": 1732528626606,
"updated": 1740831984389,
"link": null,
"locked": false,
"points": [
Expand All @@ -362,7 +362,7 @@
],
[
-145.19927314579581,
-21.285474263868366
-10.285474263868366
],
[
-299,
Expand All @@ -372,13 +372,15 @@
"lastCommittedPoint": null,
"startBinding": {
"elementId": "1CUX3csO6NXxDDXe95iEy",
"focus": 0.11346363512743769,
"gap": 1
"focus": 0.21119870148440137,
"gap": 1,
"fixedPoint": null
},
"endBinding": {
"elementId": "CpW7nu1vqtnIb2UrygagX",
"focus": -0.4746472712525178,
"gap": 11.88476568749968
"focus": -0.6302384885002369,
"gap": 11.88476568749968,
"fixedPoint": null
},
"startArrowhead": "arrow",
"endArrowhead": "arrow"
Expand Down Expand Up @@ -642,42 +644,44 @@
},
{
"type": "arrow",
"version": 506,
"versionNonce": 446414578,
"version": 559,
"versionNonce": 1148547180,
"index": "b9T",
"isDeleted": false,
"id": "fHeNea3n2b52g848widIY",
"fillStyle": "solid",
"strokeWidth": 4,
"strokeStyle": "solid",
"roughness": 1,
"roughness": 0,
"opacity": 100,
"angle": 0,
"x": 1219,
"y": 437.7795801888765,
"strokeColor": "#1e1e1e",
"strokeColor": "#868e96",
"backgroundColor": "transparent",
"width": 298,
"height": 59.931959236998864,
"seed": 250646898,
"seed": 1699953388,
"groupIds": [],
"frameId": null,
"roundness": {
"type": 2
},
"boundElements": [],
"updated": 1732529214122,
"updated": 1740831993523,
"link": null,
"locked": false,
"startBinding": {
"elementId": "1CUX3csO6NXxDDXe95iEy",
"focus": -0.06566853465828919,
"gap": 1
"focus": -0.21904813762034608,
"gap": 1,
"fixedPoint": null
},
"endBinding": {
"elementId": "tLXgfyKQzA1XBPoNahlQY",
"focus": 0.3609456866146439,
"gap": 1
"focus": 0.488506511786804,
"gap": 1,
"fixedPoint": null
},
"lastCommittedPoint": null,
"startArrowhead": "arrow",
Expand All @@ -688,8 +692,8 @@
0
],
[
-142.19927314579581,
36.38844977806605
-156.19927314579581,
19.388449778066047
],
[
-298,
Expand Down Expand Up @@ -1249,25 +1253,25 @@
"width": 329.6469879942658,
"height": 14.631182736740925,
"angle": 0,
"strokeColor": "#1e1e1e",
"strokeColor": "#868e96",
"backgroundColor": "#ffffff",
"fillStyle": "solid",
"strokeWidth": 4,
"strokeStyle": "solid",
"roughness": 1,
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": "b9f",
"roundness": {
"type": 2
},
"seed": 187398194,
"version": 453,
"versionNonce": 476171250,
"seed": 1264218092,
"version": 456,
"versionNonce": 1642403668,
"isDeleted": false,
"boundElements": [],
"updated": 1732529229592,
"updated": 1740831997959,
"link": null,
"locked": false,
"points": [
Expand Down Expand Up @@ -1306,7 +1310,7 @@
"width": 0.6172952991352872,
"height": 65,
"angle": 0,
"strokeColor": "#1e1e1e",
"strokeColor": "#868e96",
"backgroundColor": "#ffffff",
"fillStyle": "solid",
"strokeWidth": 4,
Expand All @@ -1320,11 +1324,11 @@
"type": 2
},
"seed": 593762350,
"version": 210,
"versionNonce": 956606318,
"version": 212,
"versionNonce": 1573447636,
"isDeleted": false,
"boundElements": [],
"updated": 1732529183419,
"updated": 1740832007275,
"link": null,
"locked": false,
"points": [
Expand Down
Loading

0 comments on commit 505bfc7

Please sign in to comment.