Skip to content

Commit

Permalink
Review and update client deployment documentation (#951)
Browse files Browse the repository at this point in the history
Major overhaul.

Significant changes include:
- Reorganized content so that it better matches the sequence that users
will follow.
- Added Tabbed command blocks for commands where multiple platforms can
be used.
- Updates to macOS including additional info such as how to jump the
security hurdles.
- Added more info showing how to verify service installation status on
each platform.
- Added section for MSI repacking using the CLI.
- Added section showing where to get client configs in the GUI.
- Removed `--sysv` option and explained which init systems we handle.
- Refreshed outdated screenshots.
- Added GIF animations as they are more engaging than terminal
screenshots.
- Generally clarified as much as possible, added extra notes and many
links to related materials.
- Some spelling fixes (American spelling preferred over British).
- Update image creation guidelines to include terminal session
recordings.
- Start work on prose style guidelines doc (in /dev).

The client deployment page is really very long now and will need to be
split up in future.
  • Loading branch information
predictiple authored Dec 1, 2024
1 parent 459a165 commit eeb42a7
Show file tree
Hide file tree
Showing 37 changed files with 2,443 additions and 436 deletions.
22 changes: 22 additions & 0 deletions .wordlist.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1590,3 +1590,25 @@ tracee
--------------------------------------------------------------------------------
datetime

<url-free> content/docs/deployment/clients/_index.md
--------------------------------------------------------------------------------
AutoUpdate
FreeBSD
Glibc
Intune
Jamf
MDM
macOS
OpenRC
Romanitho
SysVinit
Toolset
WiX
XP
configs
dmg
init
subcommand
toolset
toolsets
wix
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,7 @@ through a number of steps:
1. The writeback file is created with a new client private key (and a
client ID).
2. The client communicates with the server but receives a 406
status. This initiates the enrolment flow.
status. This initiates the enrollment flow.
3. The server schedules an Interrogate flow on the client, which
issues a number of VQL queries.
4. We can now search for the client using the GUI search box.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -203,7 +203,7 @@ through a number of steps:
1. The writeback file is created with a new client private key (and a
client ID).
2. The client communicates with the server but receives a 406 status.
This initiates the enrolment flow.
This initiates the enrollment flow.
3. The server schedules an Interrogate flow on the client, which issues
a number of VQL queries.
4. We can now search for the client using the GUI search box.
Expand Down
874 changes: 616 additions & 258 deletions content/docs/deployment/clients/_index.md

Large diffs are not rendered by default.

281 changes: 281 additions & 0 deletions content/docs/deployment/clients/client_config_orgs.excalidraw

Large diffs are not rendered by default.

10 changes: 10 additions & 0 deletions content/docs/deployment/clients/client_config_orgs.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
315 changes: 315 additions & 0 deletions content/docs/deployment/clients/create_msi_add.excalidraw

Large diffs are not rendered by default.

10 changes: 10 additions & 0 deletions content/docs/deployment/clients/create_msi_add.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
186 changes: 186 additions & 0 deletions content/docs/deployment/clients/create_msi_uploaded.excalidraw

Large diffs are not rendered by default.

10 changes: 10 additions & 0 deletions content/docs/deployment/clients/create_msi_uploaded.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified content/docs/deployment/clients/image34.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified content/docs/deployment/clients/image36.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified content/docs/deployment/clients/image37.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed content/docs/deployment/clients/image38.png
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added content/docs/deployment/clients/macos_fda.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
144 changes: 144 additions & 0 deletions content/docs/deployment/clients/remote_upgrade_msi.excalidraw

Large diffs are not rendered by default.

Binary file not shown.
10 changes: 10 additions & 0 deletions content/docs/deployment/clients/remote_upgrade_msi.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
312 changes: 312 additions & 0 deletions content/docs/deployment/clients/remote_upgrade_msi_2.excalidraw

Large diffs are not rendered by default.

Binary file not shown.
10 changes: 10 additions & 0 deletions content/docs/deployment/clients/remote_upgrade_msi_2.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
50 changes: 50 additions & 0 deletions content/docs/deployment/clients/run_client_manual.tape
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
Output ./run_client_manual.gif
# Output ./run_client_manual.mp4

# Settings:
Set Shell bash
Set FontSize 16
Set FontFamily "Iosevka Term"
Set Height 800
Set Width 1200
Set LetterSpacing 1.0
Set LoopOffset 0
Set Theme "deep"
Set PlaybackSpeed 1.0
Set Margin 0
Set Padding 20
# Set MarginFill "#ffffff"
# Set BorderRadius 10

# Setup
Hide
Type "PS1='\[\033[1;34m\]root@computer \[\033[1;32m\]~ \[\033[1;34m\]# \[$(tput sgr0)\]'"
Enter
Type "alias velociraptor='velociraptor-v0.73.3-linux-amd64'"
Enter
Type "find /tmp -type f -iname 'Velociraptor.writeback*' -delete"
Enter
Type "sed -i 's|/home/me/Sync/zxcv/servers/velociraptor/datastore3|/tmp|g' ./client.config.yaml"
Enter
Type "clear"
Enter
Sleep 1s
Show
Sleep 1s

# Type a command in the terminal.
Type "velociraptor --config client.config.yaml client -v"

# Pause for dramatic effect...
Sleep 2s

Set PlaybackSpeed 0.5

# Run the command by pressing enter.
Enter

Sleep 565ms
Screenshot ./run_client_manual.png

# Admire the output for a bit.
Sleep 3s
Binary file added content/docs/deployment/clients/wix_build.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
57 changes: 57 additions & 0 deletions content/docs/deployment/clients/wix_build.tape
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
Output ./wix_build.gif
Output ./wix_build.mp4

# Settings:
Set Shell bash
Set FontSize 16
Set FontFamily "Iosevka Term"
Set Height 800
Set Width 1200
Set LetterSpacing 1.0
Set LoopOffset 0
Set Theme "deep"
Set PlaybackSpeed 1.0
Set Margin 0
Set Padding 20
# Set MarginFill "#ffffff"
# Set BorderRadius 10

# Setup
Hide
Type "ssh windoze"
Enter
Sleep 2s
Type "prompt"
Enter
Type "cd Downloads\wix"
Enter
Type "cls"
Enter
Sleep 1s
Show

Sleep 1s

# Type a command in the terminal.
Type "build_amd64.bat"

# Pause for dramatic effect...
Sleep 2s

# Run the command by pressing enter.
Enter

Sleep 10s
Screenshot ./wix_build.png

# Admire the output for a bit.
Sleep 10s

Type "dir *.msi"
Enter

Sleep 2s

Hide
Type "exit"
Enter
22 changes: 11 additions & 11 deletions content/exchange/artifacts/DeleteClientLabel.yaml
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
name: Server.Utils.DeleteClientLabel
author: Matt Green - @mgreen27
description: |
This artifact completely removes a client from the data store if a configured
This artifact completely removes a client from the data store if a configured
label is set.
We reccomend running as a server artifact then if happy with actions add as an
action for monitoring.
We reccomend running as a server artifact then if happy with actions add as an
action for monitoring.
Be careful with this one: there is no way to recover old
data. However, if the client still exists, it will just
automatically re-enrol when it next connects. You will still be able
automatically re-enroll when it next connects. You will still be able
to talk to it, it is just that old collected data is deleted.
type: SERVER
Expand All @@ -24,7 +24,7 @@ parameters:

sources:
- query: |
LET to_remove = SELECT
LET to_remove = SELECT
client_id AS ClientId,
os_info.hostname as Hostname,
timestamp(epoch=first_seen_at) AS FirstSeen,
Expand All @@ -39,11 +39,11 @@ sources:
os_info.mac_addresses as mac_addresses
FROM clients()
WHERE LabelToDelete IN labels
LET deleted_files <= SELECT *
LET deleted_files <= SELECT *
FROM client_delete(client_id=to_remove.ClientId, really_do_it=ReallyDoIt)
SELECT *,
SELECT *,
{
SELECT vfs_path
FROM deleted_files
Expand Down
2 changes: 1 addition & 1 deletion content/exchange/artifacts/Exchange.Label.User.yaml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name: Exchange.Label.User
description: |
This artifact watches for new client enrolments and automatically
This artifact watches for new client enrollments and automatically
label the client with the required label if the user exists.
This artifact can be the starting point for automatically labeling
Expand Down
82 changes: 0 additions & 82 deletions dev/Notebooks.UpdateExcalidrawFontMapping.yaml

This file was deleted.

Loading

0 comments on commit eeb42a7

Please sign in to comment.