Axonius-api-client

<!-- MarkdownTOC -->

- [Feature: Reduce logging levels in certificate land](feature-reduce-logging-levels-in-certificate-land)

<!-- /MarkdownTOC -->

Feature: Reduce logging levels in certificate land

All logging from cert_human is now done at debug level.

<!-- MarkdownTOC -->

- [Bugfix: Python 3.8.x errors](bugfix-python-38x-errors)
- [Feature: Add include history dates when getting assets](feature-add-include-history-dates-when-getting-assets)

<!-- /MarkdownTOC -->


Bugfix: Python 3.8.x errors

Trying to use the API client on Python 3.8.x would cause exception like:


TypeError: Optional[t] requires a single type. Got Field(name=None....


Cause: Global namespace confusion with class attributes named 'type' and using a type hint like t.Optional[type].
Resolution: Replaced with t.Any.


Feature: Add include history dates when getting assets

New axonshell argument:


axonshell devices get --include-dates


Will add history_date and current_date to as columns to each asset in output.
What's Changed
* [SA-3427] Add Include Dates (History and Current) by bryce-ax in https://github.com/Axonius/axonius_api_client/pull/227
* 4.60.1 by lifehackjim in https://github.com/Axonius/axonius_api_client/pull/228
* 4.60.1 by lifehackjim in https://github.com/Axonius/axonius_api_client/pull/229

New Contributors
* bryce-ax made their first contribution in https://github.com/Axonius/axonius_api_client/pull/227

**Full Changelog**: https://github.com/Axonius/axonius_api_client/compare/4.60.0...4.60.1

<!-- MarkdownTOC -->

- [Breaking change: You can no longer remove queries from Enforcement Set](breaking-change-you-can-no-longer-remove-querys-from-enforcement-set)
- [Feature: Folder support](feature-folder-support)
- [Axonshell changes](axonshell-changes)
- [API Changes](api-changes)
- [Feature: Add ability to use username and password for credentials](feature-add-ability-to-use-username-and-password-for-credentials)
- [Axonshell changes](axonshell-changes-1)
- [API changes](api-changes-1)
- [Feature: Get the API keys from an Axonius instance and write them to a file](feature-get-the-api-keys-from-an-axonius-instance-and-write-them-to-a-file)
- [Feature: Add log filtering to avoid potential credential storage](feature-add-log-filtering-to-avoid-potential-credential-storage)

<!-- /MarkdownTOC -->


Breaking change: You can no longer remove queries from Enforcement Set

Trying to do so will now give an error.

Feature: Folder support

This release marks the addition of support for folders for Queries and Enforcements.

Axonshell changes

Added new optional arguments --folder and --create to the following:
- axonshell devices saved-query add
- axonshell devices saved-query copy
- axonshell enforcements copy
- axonshell enforcements create
- axonshell users saved-query add
- axonshell users saved-query copy
- axonshell vulnerabilities saved-query add
- axonshell vulnerabilities saved-query copy

Added new commands:
- axonshell devices saved-query update-folder
- axonshell enforcements update-description
- axonshell enforcements update-folder
- axonshell users saved-query update-folder
- axonshell vulnerabilities saved-query update-folder

Added new command group:
- axonshell folders
- axonshell folders queries
- axonshell folders enforcements

Each command group under folders exposes the same set of commands for working with folders for their respective object types:

- create: Create a folder.
- delete: Delete a folder.
- find: Find a folder.
- get-tree: Get a tree view of all subfolders and their...
- move: Move a folder.
- rename: Rename a folder.
- search-objects: Search for objects in a folder.
- search-objects-copy: Search for objects in a folder and make copies...
- search-objects-delete: Search for objects in a folder and delete them.
- search-objects-move: Search for objects in a folder and move them.

API Changes

New API module under client:
- client.folders -> axonius_api_client.api.folders.Folders
- client.folders.queries -> axonius_api_client.api.folders.FoldersQueries
- client.folders.enforcements -> axonius_api_client.api.folders.FoldersEnforcements

Each API module exposes the same set of methods for working with folders for their respective object types:
- api_endpoint_group: Endpoint group to use for this folders object type
- get: Get the root for this folders object type
- get_cached: Get the root for this folders object type
- get_tree: Get a tree view of all subfolders and their objects
- find: Get a folder by path, id, or folder model for this folders object type
- find_cached: Get a folder by path, id, or folder model for this folders object type
- search_objects: Search for objects in a folder
- search_objects_copy: Search for objects in a folder and copy them, optionally to a different folder
- search_objects_move: Search for objects in a folder and move themto a different folder.
- search_objects_delete: Search for objects in a folder and move themto a different folder.
- create: Create a folder
- rename: Rename a folder
- move: Move a folder
- delete: Delete a folder
- `_get`: direct api method to get root folders
- `_rename`: direct api method to rename a folder
- `_move`: direct api method to move a folder
- `_create`: direct api method to create a folder
- `_delete`: direct api method to delete a folder


Feature: Add ability to use username and password for credentials

Axonshell changes

A new option is available to be used at the beginning of the command line:

text
-creds, --credentials / -keys, --keys
Treat key as Username and secret as password
[env var: AX_CREDENTIALS; default: keys]
`

This option, when used like:

axonshell -creds devices count


Will treat the value stored in --key or AX_KEY as username, and the value stored in --secret or AX_SECRET as the password.

API changes

Connect has a new argument:

python
credentials: bool = False


If this is True, key is treated as username and secret is treated as password and instead of using the Auth module ApiKey, it will use the new Auth module Credentials.

Credentials logs in with username and password, then fetches the api key and secret and uses that for the duration of the session.

Feature: Get the API keys from an Axonius instance and write them to a file

A new command group has been added to Axonshell:

text
Usage: axonshell account [OPTIONS] COMMAND [ARGS]...

Group: Account commands.

Options:
--help Show this message and exit.

Commands:
get-api-keys Get the API keys for the current user.
signup Perform the initial signup to an instance.
use-password-reset-token Use a password reset token.
write-config Create/Update a '.env' file with url, key,...



The signup, use-password-reset-token, and write-config commands are just copied over from axonshell tools.

The get-api-key command is a new command altogether:

text
Usage: axonshell account get-api-keys [OPTIONS]

Get the API keys for the current user.

Options:
-u, --url URL URL of an Axonius instance [env var:
AX_URL; required]
-k, --key KEY API Key of user in an Axonius instance [env
var: AX_KEY; required]
-s, --secret SECRET API Secret of user in an Axonius instance
[env var: AX_SECRET; required]
-xf, --export-format [json|str|env]
Format of to export data in [env var:
AX_EXPORT_FORMAT; default: str]
-e, --env TEXT Path to .env file when --export-format==env
[env var: AX_ENV; default: .env]
--help Show this message and exit.


You can use this with the new --credentials option and have it prompt you for key (provide username), prompt you for secret (provide password) then create your .env file for you:


axonshell -creds account get-api-keys --url 1.1.1.1 --export-format env


Feature: Add log filtering to avoid potential credential storage

Created a logging formatter in axonius_api_client.logs:
python

class HideFormatter(logging.Formatter):
"""Hide the rest of the line for any lines against :attr:`HIDE_REGEX`."""

HIDE_ENABLED: bool = True
"""Enable hiding of matches to HIDE_REGEX."""
HIDE_REGEX: t.Pattern = re.compile(r"(password|secret).*", re.I)
"""Pattern of sensitive info to hide."""
HIDE_REPLACE: str = r"\1 ...REST OF LINE HIDDEN..."
"""Value to replace matches to HIDE_REGEX with."""


If any line in the logging output contains the word password or secret, the rest of the line after those words will be hidden from the logging system.

What's Changed
* backmerge 4.50.3 by lifehackjim in https://github.com/Axonius/axonius_api_client/pull/222
* 4.60.0 by lifehackjim in https://github.com/Axonius/axonius_api_client/pull/223
* 4.60.0 SA-3545 SA-3419 by lifehackjim in https://github.com/Axonius/axonius_api_client/pull/224
* More features for 4.60.0 by lifehackjim in https://github.com/Axonius/axonius_api_client/pull/226
* Bugfixes for QA gold release SA-3419 by lifehackjim in https://github.com/Axonius/axonius_api_client/pull/225


**Full Changelog**: https://github.com/Axonius/axonius_api_client/compare/4.50.3...4.60.0

<!-- MarkdownTOC -->

- [BugFix: SavedQuery predefined returning None](bugfix-savedquery-predefined-returning-none)

<!-- /MarkdownTOC -->


BugFix: SavedQuery predefined returning None

When getting Saved Queries, an error can sometimes occur where predefined is None instead of a boolean. Schema modified to allow none.

What's Changed
* Allow predefined to be null in saved queries. by nate-axonius in https://github.com/Axonius/axonius_api_client/pull/216
* Bump werkzeug from 2.0.3 to 2.2.3 by dependabot in https://github.com/Axonius/axonius_api_client/pull/217
* back-merge patch by lifehackjim in https://github.com/Axonius/axonius_api_client/pull/219
* 4.50.3 by lifehackjim in https://github.com/Axonius/axonius_api_client/pull/221

**Full Changelog**: https://github.com/Axonius/axonius_api_client/compare/4.50.2...4.50.3

<!-- MarkdownTOC -->

- [KNOWN BUG: Making private copies of Saved Queries that are public](known-bug-making-private-copies-of-saved-queries-that-are-public)
- [Bugfix: Remove spurious json serialization errors in logs](bugfix-remove-spurious-json-serialization-errors-in-logs)
- [Bugfix: Reduce warnings from extra attributes](bugfix-reduce-warnings-from-extra-attributes)
- [Bugfix: switch all API endpoints for saved queries from /views/ path to /queries/ path](bugfix-switch-all-api-endpoints-for-saved-queries-from-views-path-to-queries-path)
- [Bugfix: axonshell devices count can sometimes throw an error:](bugfix-axonshell-devices-count-can-sometimes-throw-an-error)
- [Bugfix: Bug in enforcements schedule_weekly logic](bugfix-bug-in-enforcements-schedule_weekly-logic)
- [Features: multiple dashboard spaces and chart features](features-multiple-dashboard-spaces-and-chart-features)

<!-- /MarkdownTOC -->


KNOWN BUG: Making private copies of Saved Queries that are public

- Currently the API Client does not yet know how to work with folders, and private saved queries can not be saved
in a shared folder (the default folder). The next version will be adding support for working with folders.

Bugfix: Remove spurious json serialization errors in logs

- Logging request and/or response bodies will no longer generate errors when bodies are empty

Bugfix: Reduce warnings from extra attributes

- Extra attribute warnings serve as a notice that the version of the API client being used does not know
about a schema change in an object presented by the Axonius API. They serve as a helpful notice that you
may need to update your API client to ensure compatibility with the version of Axonius that is being utilized.
- Extra attributes now have their own warning class: axonius_api_client.exceptions.ExtraAttributeWarning
- Extra attribute warnings will now only happen once per schema
- Extra attribute warnings can be disabled entirely using OS environment variable AX_EXTRA_WARN="no"
- Extra attribute warning message updated to:
text
To silence these warnings please upgrade to latest API client.
If there is not a newer version available yet, you can disable these warnings using:
- from command line, use OS environment variable AX_EXTRA_WARN='no'
- or from python, use warnings module:
import warnings, axonius_api_client
warnings.filterwarnings(action="ignore", category=axonius_api_client.exceptions.ExtraAttributeWarning)

- As part of this effort, all schemas in the API Client have been updated to match the schema definitions in the Axonius 4.8.0.4 API

Bugfix: switch all API endpoints for saved queries from /views/ path to /queries/ path

- The /views/ path is deprecated and problematic.
- A large number of back end changes to saved query schemas and private methods were made to support this effort.

Bugfix: axonshell devices count can sometimes throw an error:

- Running:
shell

axonshell devices count --history-days-ago 1


- Would produce an error:
text
min() arg is an empty sequence


- Implemented check for None when no history is available

Bugfix: Bug in enforcements schedule_weekly logic

- Running:
shell
axonshell enforcements update-schedule-weekly -r 1 -sh 23 -sm 3 --value xyz


- Would produce an error:
text
Enforcements.update_schedule_weekly() got an unexpected keyword argument 'schedule_hour'"


- Updated the keywords being used for the click arguments from "schedule_hour" and "schedule_minute" to "hour" and "minute"

Features: multiple dashboard spaces and chart features

- CLI command group added: axonshell spaces
- New commands in axonshell spaces:
- export: Export Dashboard Spaces.
- export-charts-to-csv: Export Multiple Charts to CSV.
- import: Import Dashboard Spaces.

- API model added: axonius_api_client.api.system.dashboard_spaces.DashboardSpaces
- Connect now has a new property to access the new API model: connect.dashboard_spaces
- Methods in axonius_api_client.api.system.dashboard_spaces.DashboardSpaces:
- get: get all dashboard space objects
- export_charts_to_csv: export charts to CSV format
- export_charts_to_csv_path: exports charts to CSV format and save to files in a directory
- export_spaces: export spaces and their charts and their queries to a JSON format
- import_spaces: import spaces and their charts and their queries from a JSON export
- get_exportables: get a list of all exportable space names
- load_export_data: load a JSON export into a dataclass and validate it
- _get_exportables: direct api method to get all exportable space names
- _get: direct api method to get all dashboard space objects
- _get_single: direct api method to get a single dashboard space object along with it's chart objects
- _export_chart_csv: direct api method to export a chart to CSV
- _import_spaces: direct api method to import a JSON export
- _export_spaces: direct api method to create a JSON export

What's Changed
* 4.50.2 by lifehackjim in https://github.com/Axonius/axonius_api_client/pull/214
* 4.50.2 by lifehackjim in https://github.com/Axonius/axonius_api_client/pull/215


**Full Changelog**: https://github.com/Axonius/axonius_api_client/compare/4.50.1...4.50.2

<!-- MarkdownTOC -->

- [Bugfix: Permission errors when using API client with 'Viewer' role](bugfix-permission-errors-when-using-api-client-with-viewer-role)
- [Bugfix: Version not accessible when using API Client with 'Viewer' role](bugfix-version-not-accessible-when-using-api-client-with-viewer-role)
- [Bugfix: Adapter Fetch History schema changes](bugfix-adapter-fetch-history-schema-changes)
- [Bugfix: Adapter Fetch History Filters schema changes](bugfix-adapter-fetch-history-filters-schema-changes)
- [Bugfix: Preferred fields not being populated when using explode-entities](bugfix-preferred-fields-not-being-populated-when-using-explode-entities)
- [Axonshell reproduction without exploding](axonshell-reproduction-without-exploding)
- [Axonshell reproduction with exploding](axonshell-reproduction-with-exploding)
- [Axonshell reproduction with fix](axonshell-reproduction-with-fix)

<!-- /MarkdownTOC -->

Bugfix: Permission errors when using API client with 'Viewer' role

- Endpoint being used for validation requires 'View system settings' permission
on users assigned role
- Added new endpoint: ApiEndpoints.system_settings.get_constants
- Switched login verification endpoint from
`ApiEndpoints.system_settings.meta_about` to `ApiEndpoints.system_settings.get_constants`

Bugfix: Version not accessible when using API Client with 'Viewer' role

- Added error:bool = True to client.meta.about()
- if error=False, errors in calls to get about metadata are caught and thrown away
- Changed Connect banner string to get about metadata with error=False
- Connect banner string changed to show 'version: unknown (no permissions)' if about
metadata is empty

Bugfix: Adapter Fetch History schema changes

- new field: discovery_id

Bugfix: Adapter Fetch History Filters schema changes

- new field: discoveries_filter
- new argument for client.adapters.get_fetch_history_generator:
`discoveries: OPT_STR_RE_LISTY = None`
- new argument for axonshell adapters:
`-fd/--filter-discoveries`

Bugfix: Preferred fields not being populated when using explode-entities

Axonshell reproduction without exploding

Get 1 asset with 2 adapters without exploding entities:

bash
axonshell devices get \
--field 'hostname_preferred' \
--wiz simple 'adapters count_equals 2' \
--max-rows 1 \
--export-file 'not_exploded.json' \
--export-overwrite


Output of not_exploded.json with one asset where
'specific_data.data.hostname_preferred' field value is not empty:

json
[
{
"adapter_list_length": 2,
"adapters": [
"tanium_adapter",
"tanium_asset_adapter"
],
"internal_axon_id": "e6edbb949369e353d735d78ebf2deb44",
"specific_data.data.hostname": [
"ip-10-0-2-213"
],
"specific_data.data.hostname_preferred": "ip-10-0-2-213",
"specific_data.data.last_seen": "Wed, 26 Oct 2022 12:31:59 GMT",
"specific_data.data.network_interfaces.ips": [
"10.0.2.213",
"fe80::4ba:77ff:fed7:336c"
],
"specific_data.data.network_interfaces.mac": [
"06:BA:77:D7:33:6C"
],
"specific_data.data.os.type": [
"Linux"
]
}
]


Axonshell reproduction with exploding

Get 1 asset with 2 adapters and explode entities:

bash
axonshell devices get \
--field 'hostname_preferred' \
--wiz simple 'adapters count_equals 2' \
--max-rows 1 \
--explode-entities \
--export-file 'exploded.json' \
--export-overwrite


Output of exploded.json where each exploded assets
'specific_data.data.hostname_preferred' field value is empty:

json
[
{
"adapters": "tanium_adapter",
"adapter_asset_entities_info": null,
"adapter_list_length": 2,
"internal_axon_id": "e6edbb949369e353d735d78ebf2deb44",
"meta_data.client_used": "63753df13ac032cb043f72e9",
"specific_data.data.hostname": "ip-10-0-2-213",
"specific_data.data.hostname_preferred": null,
"specific_data.data.last_seen": "Wed, 26 Oct 2022 12:31:59 GMT",
"specific_data.data.name": null,
"specific_data.data.network_interfaces.ips": [
"10.0.2.213"
],
"specific_data.data.network_interfaces.mac": null,
"specific_data.data.os.type": null,
"unique_adapter_names_details": ""
},
{
"adapters": "tanium_asset_adapter",
"adapter_asset_entities_info": null,
"adapter_list_length": 2,
"internal_axon_id": "e6edbb949369e353d735d78ebf2deb44",
"meta_data.client_used": "63753e2df6170824de0193f5",
"specific_data.data.hostname": "ip-10-0-2-213",
"specific_data.data.hostname_preferred": null,
"specific_data.data.last_seen": "Wed, 26 Oct 2022 12:00:04 GMT",
"specific_data.data.name": null,
"specific_data.data.network_interfaces.ips": [
"10.0.2.213",
"fe80::4ba:77ff:fed7:336c"
],
"specific_data.data.network_interfaces.mac": "06:BA:77:D7:33:6C",
"specific_data.data.os.type": "Linux",
"unique_adapter_names_details": ""
}
]


Axonshell reproduction with fix

bash
axonshell devices get \
--field 'hostname_preferred' \
--wiz simple 'adapters count_equals 2' \
--max-rows 1 \
--explode-entities \
--export-file 'exploded.json' \
--export-overwrite


Output of exploded.json where each exploded assets
'specific_data.data.hostname_preferred' field value is not empty:

json
[
{
"adapters": "tanium_adapter",
"adapter_asset_entities_info": null,
"adapter_list_length": 2,
"internal_axon_id": "e6edbb949369e353d735d78ebf2deb44",
"meta_data.client_used": "63753df13ac032cb043f72e9",
"specific_data.data.hostname": "ip-10-0-2-213",
"specific_data.data.hostname_preferred": "ip-10-0-2-213",
"specific_data.data.last_seen": "Wed, 26 Oct 2022 12:31:59 GMT",
"specific_data.data.name": null,
"specific_data.data.network_interfaces.ips": [
"10.0.2.213"
],
"specific_data.data.network_interfaces.mac": null,
"specific_data.data.os.type": null,
"unique_adapter_names_details": ""
},
{
"adapters": "tanium_asset_adapter",
"adapter_asset_entities_info": null,
"adapter_list_length": 2,
"internal_axon_id": "e6edbb949369e353d735d78ebf2deb44",
"meta_data.client_used": "63753e2df6170824de0193f5",
"specific_data.data.hostname": "ip-10-0-2-213",
"specific_data.data.hostname_preferred": "ip-10-0-2-213",
"specific_data.data.last_seen": "Wed, 26 Oct 2022 12:00:04 GMT",
"specific_data.data.name": null,
"specific_data.data.network_interfaces.ips": [
"10.0.2.213",
"fe80::4ba:77ff:fed7:336c"
],
"specific_data.data.network_interfaces.mac": "06:BA:77:D7:33:6C",
"specific_data.data.os.type": "Linux",
"unique_adapter_names_details": ""
}
]


What's Changed
* 4.50.1 by lifehackjim in https://github.com/Axonius/axonius_api_client/pull/213


**Full Changelog**: https://github.com/Axonius/axonius_api_client/compare/4.50.0...4.50.1