From fb54b43cba091257939d0196384f6e86fed322eb Mon Sep 17 00:00:00 2001 From: Cecilia Stevens <63068179+ceciliastevens@users.noreply.github.com> Date: Fri, 26 Feb 2021 10:52:02 -0600 Subject: [PATCH 1/4] added deactivate devices guide --- docs/guides.md | 1 + docs/userguides/deactivatedevices.md | 65 ++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+) create mode 100644 docs/userguides/deactivatedevices.md diff --git a/docs/guides.md b/docs/guides.md index 6aa4243e6..d1677cca7 100644 --- a/docs/guides.md +++ b/docs/guides.md @@ -5,3 +5,4 @@ * [Ingest file events or alerts into a SIEM](userguides/siemexample.md) * [Manage detection list users](userguides/detectionlists.md) * [Manage legal hold users](userguides/legalhold.md) +* [Clean up your environment by deactivating devices](userguides/deactivatedevices.md) \ No newline at end of file diff --git a/docs/userguides/deactivatedevices.md b/docs/userguides/deactivatedevices.md new file mode 100644 index 000000000..62e100f96 --- /dev/null +++ b/docs/userguides/deactivatedevices.md @@ -0,0 +1,65 @@ +# Clean up your environment by deactivating devices + +Your Code42 environment may contain many old devices that are no longer active computers, and that have not connected to Code42 in quite some time. In order to clean up your environment, you can use the CLI to deactivate these devices in bulk. + +## Generating a list of devices + +You can generate a list of devices using `code42 devices list`. By default it will display the list of devices at the command line, but you can also output it in a number of file formats. For example, to generate a CSV of devices in your environment, use this command: + +``` +code42 devices list -f CSV +``` + +To save to a file, redirect the output to a file in your shell: + +``` +code42 devices list -f CSV > output.csv +``` + +### Filtering the list + +You can filter or edit the list of devices in your spreadsheet or text editor of choice, but the CLI has some parameters built in that can help you to filter the list of devices to just the ones you want to deactivate. To see a full list of available parameters, run `code42 devices list -h`. + +Here are some useful paramaters you may wish to leverage when curating a list of devices to deactivate: + +* `--last-connected-before DATE|TIMESTAMP|SHORT_TIME` - allows you to only see devices that have not connected since a particular date. You can also use a timestamp or short time format, for example `30d`. +* `--exclude-most-recently-connected INTEGER` - allows you to exclude the most recently connected device (per user) from the results. This allows you to ensure that every user is left with at least N device(s), regardless of how recently they have connected. +* `--created-before DATE|TIMESTAMP|SHORT_TIME` - allows you to only see devices created before a particular date. + +## Deactivating devices + +Once you have a list of devices that you wish to remove, you can run the `code42 devices bulk deactivate` command: + +``` +code42 devices bulk deactivate list_of_devices.csv +``` + +The device list must be a file in CSV format containing a `guid` column with the unique identifier of the devices to be deactivated. The deactivate command can also accept some optional parameters: + +* `--change-device-name` - prepends `deactivated_` to the beginning of the device name, allowing you to have a record of which devices were deactivated by the CLI and when. +* `--purge-date yyyy-MM-dd` - allows you to change the date on which the deactivated devices' archives will be purged from cold storage. + +To see a full list of available options, run `code42 devices bulk deactivate -h`. + +The `code42 devices bulk deactivate` command will output the input you gave it, plus a column indicating the success or failure of the deactivation. To change the format of this output, use the `-f` or `--format` option. + +You can also redirect the output to a file, for example: + +``` +code42 devices bulk deactivate devices_to_deactivate.csv -f CSV > deactivation_results.csv +``` + +Deactivation will fail if the user running the command does not have permission to deactivate the device, or if the user owning the device is on legal hold. + + +### Generating the list and deactivating in a single command + +You can also pipe the output of `code42 devices list` directly to `code42 devices bulk deactivate`. When using a pipe, make sure to use `-` as the input argument for `code42 devices bulk deactivate` to indicate that it should read from standard input. + +Here is an example: + +``` +code42 devices list --last-connected-before 365d --exclude-most-recently-connected 1 -f CSV | code42 devices bulk deactivate - -f CSV > deactivation_results.csv +``` + +This lists all devices that have not connected within a year _and_ are not a user's most-recently-connected device, and then attempts to deactivate them. \ No newline at end of file From bf44475f7e9af6f6b67f71e53f23e55152507e9c Mon Sep 17 00:00:00 2001 From: Cecilia Stevens <63068179+ceciliastevens@users.noreply.github.com> Date: Fri, 26 Feb 2021 10:58:51 -0600 Subject: [PATCH 2/4] style --- docs/guides.md | 2 +- docs/userguides/deactivatedevices.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides.md b/docs/guides.md index d1677cca7..c24a8dec4 100644 --- a/docs/guides.md +++ b/docs/guides.md @@ -5,4 +5,4 @@ * [Ingest file events or alerts into a SIEM](userguides/siemexample.md) * [Manage detection list users](userguides/detectionlists.md) * [Manage legal hold users](userguides/legalhold.md) -* [Clean up your environment by deactivating devices](userguides/deactivatedevices.md) \ No newline at end of file +* [Clean up your environment by deactivating devices](userguides/deactivatedevices.md) diff --git a/docs/userguides/deactivatedevices.md b/docs/userguides/deactivatedevices.md index 62e100f96..4b2406446 100644 --- a/docs/userguides/deactivatedevices.md +++ b/docs/userguides/deactivatedevices.md @@ -32,7 +32,7 @@ Once you have a list of devices that you wish to remove, you can run the `code42 ``` code42 devices bulk deactivate list_of_devices.csv -``` +``` The device list must be a file in CSV format containing a `guid` column with the unique identifier of the devices to be deactivated. The deactivate command can also accept some optional parameters: @@ -62,4 +62,4 @@ Here is an example: code42 devices list --last-connected-before 365d --exclude-most-recently-connected 1 -f CSV | code42 devices bulk deactivate - -f CSV > deactivation_results.csv ``` -This lists all devices that have not connected within a year _and_ are not a user's most-recently-connected device, and then attempts to deactivate them. \ No newline at end of file +This lists all devices that have not connected within a year _and_ are not a user's most-recently-connected device, and then attempts to deactivate them. From 918759db50e3d0b5e740dfb859644a6b67a1632d Mon Sep 17 00:00:00 2001 From: Cecilia Stevens <63068179+ceciliastevens@users.noreply.github.com> Date: Fri, 26 Feb 2021 11:21:43 -0600 Subject: [PATCH 3/4] updates for line length and spelling --- docs/userguides/deactivatedevices.md | 54 ++++++++++++++++++++++------ 1 file changed, 43 insertions(+), 11 deletions(-) diff --git a/docs/userguides/deactivatedevices.md b/docs/userguides/deactivatedevices.md index 4b2406446..62793b50c 100644 --- a/docs/userguides/deactivatedevices.md +++ b/docs/userguides/deactivatedevices.md @@ -1,10 +1,17 @@ # Clean up your environment by deactivating devices -Your Code42 environment may contain many old devices that are no longer active computers, and that have not connected to Code42 in quite some time. In order to clean up your environment, you can use the CLI to deactivate these devices in bulk. +Your Code42 environment may contain many old devices that are no +longer active computers and that have not connected to Code42 in +quite some time. In order to clean up your environment, you can +use the CLI to deactivate these devices in bulk. ## Generating a list of devices -You can generate a list of devices using `code42 devices list`. By default it will display the list of devices at the command line, but you can also output it in a number of file formats. For example, to generate a CSV of devices in your environment, use this command: +You can generate a list of devices using `code42 devices list`. By +default, it will display the list of devices at the command line, +but you can also output it in a number of file formats. For +example, to generate a CSV of devices in your environment, use +this command: ``` code42 devices list -f CSV @@ -18,9 +25,14 @@ code42 devices list -f CSV > output.csv ### Filtering the list -You can filter or edit the list of devices in your spreadsheet or text editor of choice, but the CLI has some parameters built in that can help you to filter the list of devices to just the ones you want to deactivate. To see a full list of available parameters, run `code42 devices list -h`. +You can filter or edit the list of devices in your spreadsheet or +text editor of choice, but the CLI has some parameters built in +that can help you to filter the list of devices to just the ones +you want to deactivate. To see a full list of available +parameters, run `code42 devices list -h`. -Here are some useful paramaters you may wish to leverage when curating a list of devices to deactivate: +Here are some useful parameters you may wish to leverage when +curating a list of devices to deactivate: * `--last-connected-before DATE|TIMESTAMP|SHORT_TIME` - allows you to only see devices that have not connected since a particular date. You can also use a timestamp or short time format, for example `30d`. * `--exclude-most-recently-connected INTEGER` - allows you to exclude the most recently connected device (per user) from the results. This allows you to ensure that every user is left with at least N device(s), regardless of how recently they have connected. @@ -28,20 +40,27 @@ Here are some useful paramaters you may wish to leverage when curating a list of ## Deactivating devices -Once you have a list of devices that you wish to remove, you can run the `code42 devices bulk deactivate` command: +Once you have a list of devices that you wish to remove, you can +run the `code42 devices bulk deactivate` command: ``` code42 devices bulk deactivate list_of_devices.csv ``` -The device list must be a file in CSV format containing a `guid` column with the unique identifier of the devices to be deactivated. The deactivate command can also accept some optional parameters: +The device list must be a file in CSV format containing a `guid` +column with the unique identifier of the devices to be +deactivated. The deactivate command can also accept some optional +parameters: * `--change-device-name` - prepends `deactivated_` to the beginning of the device name, allowing you to have a record of which devices were deactivated by the CLI and when. * `--purge-date yyyy-MM-dd` - allows you to change the date on which the deactivated devices' archives will be purged from cold storage. To see a full list of available options, run `code42 devices bulk deactivate -h`. -The `code42 devices bulk deactivate` command will output the input you gave it, plus a column indicating the success or failure of the deactivation. To change the format of this output, use the `-f` or `--format` option. +The `code42 devices bulk deactivate` command will output the input +you gave it, plus a column indicating the success or failure of +the deactivation. To change the format of this output, use the +`-f` or `--format` option. You can also redirect the output to a file, for example: @@ -49,17 +68,30 @@ You can also redirect the output to a file, for example: code42 devices bulk deactivate devices_to_deactivate.csv -f CSV > deactivation_results.csv ``` -Deactivation will fail if the user running the command does not have permission to deactivate the device, or if the user owning the device is on legal hold. +Deactivation will fail if the user running the command does not +have permission to deactivate the device, or if the user owning +the device is on legal hold. ### Generating the list and deactivating in a single command -You can also pipe the output of `code42 devices list` directly to `code42 devices bulk deactivate`. When using a pipe, make sure to use `-` as the input argument for `code42 devices bulk deactivate` to indicate that it should read from standard input. +You can also pipe the output of `code42 devices list` directly to +`code42 devices bulk deactivate`. When using a pipe, make sure to +use `-` as the input argument for `code42 devices bulk deactivate` +to indicate that it should read from standard input. Here is an example: ``` -code42 devices list --last-connected-before 365d --exclude-most-recently-connected 1 -f CSV | code42 devices bulk deactivate - -f CSV > deactivation_results.csv +code42 devices list \ +--last-connected-before 365d \ +--exclude-most-recently-connected 1 \ +-f CSV \ +| code42 devices bulk deactivate - \ +-f CSV \ +> deactivation_results.csv ``` -This lists all devices that have not connected within a year _and_ are not a user's most-recently-connected device, and then attempts to deactivate them. +This lists all devices that have not connected within a year _and_ +are not a user's most-recently-connected device, and then attempts +to deactivate them. From a1b29fc722bf73801f9d9d45676ef9f9524e240b Mon Sep 17 00:00:00 2001 From: Cecilia Stevens <63068179+ceciliastevens@users.noreply.github.com> Date: Fri, 26 Feb 2021 15:20:13 -0600 Subject: [PATCH 4/4] address editorial suggestions --- docs/userguides/deactivatedevices.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/userguides/deactivatedevices.md b/docs/userguides/deactivatedevices.md index 62793b50c..afe641531 100644 --- a/docs/userguides/deactivatedevices.md +++ b/docs/userguides/deactivatedevices.md @@ -5,7 +5,7 @@ longer active computers and that have not connected to Code42 in quite some time. In order to clean up your environment, you can use the CLI to deactivate these devices in bulk. -## Generating a list of devices +## Generate a list of devices You can generate a list of devices using `code42 devices list`. By default, it will display the list of devices at the command line, @@ -23,7 +23,7 @@ To save to a file, redirect the output to a file in your shell: code42 devices list -f CSV > output.csv ``` -### Filtering the list +### Filter the list You can filter or edit the list of devices in your spreadsheet or text editor of choice, but the CLI has some parameters built in @@ -38,9 +38,9 @@ curating a list of devices to deactivate: * `--exclude-most-recently-connected INTEGER` - allows you to exclude the most recently connected device (per user) from the results. This allows you to ensure that every user is left with at least N device(s), regardless of how recently they have connected. * `--created-before DATE|TIMESTAMP|SHORT_TIME` - allows you to only see devices created before a particular date. -## Deactivating devices +## Deactivate devices -Once you have a list of devices that you wish to remove, you can +Once you have a list of devices that you want to remove, you can run the `code42 devices bulk deactivate` command: ``` @@ -57,10 +57,10 @@ parameters: To see a full list of available options, run `code42 devices bulk deactivate -h`. -The `code42 devices bulk deactivate` command will output the input -you gave it, plus a column indicating the success or failure of -the deactivation. To change the format of this output, use the -`-f` or `--format` option. +The `code42 devices bulk deactivate` command will output the guid +of the device to be deactivated, plus a column indicating the +success or failure of the deactivation. To change the format of +this output, use the `-f` or `--format` option. You can also redirect the output to a file, for example: @@ -73,7 +73,7 @@ have permission to deactivate the device, or if the user owning the device is on legal hold. -### Generating the list and deactivating in a single command +### Generate the list and deactivate in a single command You can also pipe the output of `code42 devices list` directly to `code42 devices bulk deactivate`. When using a pipe, make sure to