Add Communication to ImportAsset

.github/workflows/check_pr.yml

@@ -20,10 +20,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - run: pipx install poetry
-      - name: Set up Python 3.8
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: 3.8
+          python-version: "3.12"
       - name: Install dependencies
         run: poetry install --with dev,docs
       - name: Build project documentation
@@ -32,7 +32,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ "3.8", "3.9", "3.10", "3.11", "3.12" ]
+        python-version: [ "3.11", "3.12", "3.13", "3.14" ]
     steps:
       - uses: actions/checkout@v4
       - run: pipx install poetry
@@ -52,10 +52,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - run: pipx install poetry
-      - name: Set up Python 3.8
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: "3.8"
+          python-version: "3.12"
           cache: "poetry"
       - name: Install dependencies
         run: poetry install --with dev
@@ -70,15 +70,17 @@ jobs:
           client_id: ${{ secrets.STAGING_PYTHON_SDK_CLIENT_ID }}
           client_secret: ${{ secrets.STAGING_PYTHON_SDK_SECRET }}
           validate_cert: "true"
+          # Flip to "true" once the integration test console accepts asset communications
+          communications: "false"
   lints:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - run: pipx install poetry
-      - name: Set up Python 3.8
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: "3.8"
+          python-version: "3.12"
           cache: "poetry"
       - name: Install dependencies
         run: poetry install --with dev

.github/workflows/publish-docs.yml

@@ -21,10 +21,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - run: pipx install poetry
-      - name: Set up Python 3.8
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: 3.8
+          python-version: "3.12"
       - name: Install dependencies
         run: poetry install --with dev,docs
       - name: Build project documentation
@@ -47,7 +47,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.8"
+          python-version: "3.12"
       - name: Build project documentation
         uses: ./.github/actions/docsbuild
       - name: Setup Pages

.github/workflows/publish.yml

@@ -23,10 +23,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - run: pipx install poetry
-      - name: Set up Python 3.8
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: 3.8
+          python-version: "3.12"
       - name: Install dependencies
         run: poetry install --with dev,docs
       - name: Build project documentation
@@ -40,7 +40,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.8"
+          python-version: "3.12"
           cache: "poetry"
       - name: Install dependencies
         run: poetry install --with dev
@@ -72,7 +72,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: "3.8"
+        python-version: "3.12"
     - name: Install dependencies
       run: poetry install --no-interaction --no-root --without dev
     - name: Build package distributions
@@ -100,7 +100,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.8"
+          python-version: "3.12"
       - name: Build project documentation
         uses: ./.github/actions/docsbuild
       - name: Setup Pages

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+- The minimum supported Python version is now 3.11. Python 3.11 through 3.14 are supported and tested. Python 3.8 reached end of life in October 2024 and current tooling no longer builds environments for it. The package API is unchanged, so this is a direct upgrade on a supported interpreter.
+- `pydantic` now requires 1.10.25 or newer, the first 1.x release that runs on Python 3.14.
+- `runzero.Client` retries a request the server refuses with `429 Too Many Requests`, honoring the `Retry-After` header or backing off exponentially, before raising `RateLimitError`. `rate_limit_retries` and `rate_limit_backoff_seconds` on the constructor tune this; `rate_limit_retries=0` restores the previous raise-immediately behavior.
+- `RateLimitError` is raised for every 429 response and now subclasses `ClientError`, so existing `except ClientError` handlers keep catching rate limits. It carries the server's `retry_after` seconds when sent.
+- `runzero.types.ImportAsset` now supports associating aggregated traffic summaries with an asset by adding `runzero.types.Communication` values to the `ImportAsset.communications` field.
+- Naive `datetime` values on `ImportAsset`, `Software`, `Vulnerability` and `Communication` are now treated as local time and serialized with an offset. The API requires RFC 3339 timestamps with an offset and previously rejected these records at import.
+
 ## [0.8.3] - 2024-05-22
 
 - Support for longer-form CVE identifies.

DEVELOPMENT.md

@@ -112,7 +112,7 @@ Poetry is an incredibly powerful toolchain and I recommend you [read its docs](h
 1. First we need to install the codegen dependency
    * `poetry install --with codegen`
 2. Next, we can run the command to generate the pydantic models from the openapi spec
-   * `poetry run datamodel-codegen --input ./api/runzero-api.yml --field-constraints --output ./models/asset.py --target-python-version 3.8`
+   * `poetry run datamodel-codegen --input ./api/runzero-api.yml --field-constraints --output ./models/asset.py --target-python-version 3.11`
 
 ### Preparing a release
 

Makefile

@@ -116,4 +116,5 @@ init-test-configs:
 	'org_id = "" # UUID of organization associated with the above token \n' \
 	'client_id = "" # OAuth client ID for the test account \n' \
 	'client_secret = '' # OAuth client secret for the test account - enclose in single quotes \n' \
-	'validate_cert = false # bool for whether to require a valid tsl cert (should be false for dev instance) \n' >> ./test_configs.toml
+	'validate_cert = false # bool for whether to require a valid tsl cert (should be false for dev instance) \n' \
+	'communications = false # bool for whether the console accepts asset communications on import \n' >> ./test_configs.toml

examples/create_asset_in_custom_integration.py

@@ -4,7 +4,7 @@
 
 import runzero
 from runzero.api import CustomIntegrationsAdmin
-from runzero.types import ImportAsset, Tag
+from runzero.types import Communication, ImportAsset, Tag
 
 # API keys are required for using the runZero sdk. See https://www.runzero.com/docs/leveraging-the-api/
 MY_CLIENT_ID = ""  # OAuth client id. See https://console.runzero.com/account/api/clients
@@ -52,6 +52,19 @@ def main():
                 "ipAddresses": "192.168.86.1\t10.10.10.1",
                 "ipAddressesExtra": "10.10.10.4",
             },
+            # Aggregated traffic summaries, one per role and protocol over a window.
+            # Naive datetimes are treated as local time and gain an offset on upload.
+            communications=[
+                Communication(
+                    role="client",
+                    protocol="HTTPS",
+                    ports=[443],
+                    start_ts=datetime.datetime.now() - datetime.timedelta(days=1),
+                    end_ts=datetime.datetime.now(),
+                    bytes_tx=1500,
+                    bytes_rx=300,
+                ),
+            ],
         ),
     )
     print(f"created asset {asset_id}")