Merge pull request #7223 from wazuh/1483-docs-aws-improve-cold-storag…

…e-documentation

Wazuh Cloud - Cold Storage Documentation

source/cloud-service/archive-data/access.rst

@@ -14,28 +14,29 @@ To access your archive data, you need an AWS token that grants permission on the
       See the :doc:`Wazuh Cloud CLI </cloud-service/cli/index>` section to learn how to list and download your archive data automatically.
 
 
-The following example describes the steps to follow to list the files of your archive data:
+Getting your API key and the AWS token
+--------------------------------------
 
+#. Obtain your Wazuh Cloud API key by following the steps outlined in the API :doc:`Authentication </cloud-service/apis/authentication>` section.
 
-1. Before your start using the Wazuh Cloud API, you need an API key. To generate your API key, see the :ref:`Authentication <cloud_apis_auth>` section.
-
-2. Use the ``POST /storage/token`` endpoint of the :cloud-api-ref:`Wazuh Cloud API <tag/storage>` to get the AWS token and access the archive data of a specific environment. In this example, we generate an AWS token valid for 3600 seconds for environment `0123456789ab`.
+#. Use the :cloud-api-ref:`POST /storage/token <tag/storage>` API endpoint with your key to get a temporary AWS token. For example, the following request generates an AWS token valid for ``3600`` seconds that grants access to the environment archive data with ID ``012345678ab``.
 
    .. code-block::
 
       curl -XPOST https://api.cloud.wazuh.com/v2/storage/token -H "x-api-key: <YOUR_API_KEY>" -H "Content-Type: application/json" --data '
       {
-         "environment_cloud_id": "0123456789ab",
+         "environment_cloud_id": "012345678ab",
          "token_expiration": "3600"
       }'
 
    .. code-block:: console
       :class: output
+      :emphasize-lines: 7-10
 
       {
-         "environment_cloud_id": "0123456789ab",
+         "environment_cloud_id": "012345678ab",
          "aws": {
-            "s3_path": "wazuh-cloud-cold-us-east-1/0123456789ab",
+            "s3_path": "wazuh-cloud-cold-us-east-1/012345678ab",
             "region": "us-east-1",
             "credentials": {
                "access_key_id": "mUdT2dBjlHd...Gh7Ni1yZKR5If",
@@ -46,19 +47,65 @@ The following example describes the steps to follow to list the files of your ar
          }
       }
 
-3. Using the AWS-CLI tool to list the files, add the token to the AWS credentials file ``~/.aws/credentials``.
+
+
+Generating the AWS `wazuh_cloud_storage` profile
+------------------------------------------------
+
+Add the token to the AWS credentials file ``~/.aws/credentials``.
 
    .. code-block:: console
+      :emphasize-lines: 4
       
       [wazuh_cloud_storage]
       aws_access_key_id = mUdT2dBjlHd...Gh7Ni1yZKR5If
       aws_secret_access_key = qEzCk63a224...5aB+e4fC1BR0G
       aws_session_token = MRg3t7HIuoA...4o4BXSAcPfUD8
 
-4. Run the following command to list your files.
+Listing archive data
+---------------------
 
-   .. code-block:: console
-      
-      $ aws --profile wazuh_cloud_storage --region us-east-1 s3 ls wazuh-cloud-cold-us-east-1/0123456789ab
+This command lists the archive data files of the environment `012345678ab`.
+
+.. code-block:: console
+
+   # aws --profile wazuh_cloud_storage --region us-east-1 s3 ls --recursive s3://wazuh-cloud-cold-us-east-1/012345678ab/
+
+.. code-block:: none
+   :class: output
+
+   2024-04-19 17:50:06        493 012345678ab/output/alerts/2024/04/19/012345678ab_output_alerts_20240419T2050_VqaWCpX9oPfDkRpD.json.gz
+   2024-04-19 18:00:05      77759 012345678ab/output/alerts/2024/04/19/012345678ab_output_alerts_20240419T2100_kdBY42OvE9QJuiia.json.gz
+
+Examples
+--------
+
+Downloading archive data – Multiple files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This command downloads the archive data files of the environment ``012345678ab`` into the ``/home/test/`` directory.
+
+.. code-block:: console
+
+   # aws --profile wazuh_cloud_storage --region us-east-1 s3 cp --recursive s3://wazuh-cloud-cold-us-east-1/012345678ab/ /home/test/
+
+.. code-block:: none
+   :class: output
+
+   download: s3://wazuh-cloud-cold-us-east-1/012345678ab/output/alerts/2024/04/19/012345678ab_output_alerts_20240419T2050_VqaWCpX9oPfDkRpD.json.gz to output/alerts/2024/04/19/012345678ab_output_alerts_20240419T2050_VqaWCpX9oPfDkRpD.json.gz
+   download: s3://wazuh-cloud-cold-us-east-1/012345678ab/output/alerts/2024/04/19/012345678ab_output_alerts_20240419T2100_kdBY42OvE9QJuiia.json.gz to output/alerts/2024/04/19/012345678ab_output_alerts_20240419T2100_kdBY42OvE9QJuiia.json.gz
+
+
+Downloading archive data – Single file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This command downloads the ``012345678ab_output_alerts_20240419T2050_VqaWCpX9oPfDkRpD.json.gz`` file of the environment ``012345678ab`` into the directory ``/home/test``.
+
+.. code-block:: console
+
+   # aws --profile wazuh_cloud_storage --region us-east-1 s3 cp --recursive s3://wazuh-cloud-cold-us-east-1/012345678ab/012345678ab_output_alerts_20240419T2050_VqaWCpX9oPfDkRpD.json.gz /home/test/
+
+.. code-block:: none
+   :class: output
 
-You now have access to your archive data.
+   download: s3://wazuh-cloud-cold-us-east-1/012345678ab/output/alerts/2024/04/19/012345678ab_output_alerts_20240419T2050_VqaWCpX9oPfDkRpD.json.gz to ./012345678ab_output_alerts_20240419T2050_VqaWCpX9oPfDkRpD.json.gz

source/cloud-service/cli/index.rst

@@ -88,10 +88,14 @@ This command generates an AWS token to access the archive data of the environmen
 .. code-block:: none
   :class: output
 
-  The following AWS credentials will be valid until 2021-05-07 13:45:24:
+  Environment Cloud ID: '012345678ab'
+  Region: 'us-east-1'
+  S3 path: 'wazuh-cloud-cold-us-east-1/012345678ab'
+
+  The following AWS credentials will be valid until 2024-04-22 13:55:27:
   [wazuh_cloud_storage]
-  aws_access_key_id = A...Q
-  aws_secret_access_key = A...E
+  aws_access_key_id = A...M
+  aws_secret_access_key = L...0
   aws_session_token = F...Q==
 
 Listing archive data