aiq-platform-api 0.1.1__tar.gz

aiq_platform_api-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AttackIQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiq_platform_api-0.1.1/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.1
+Name: aiq-platform-api
+Version: 0.1.1
+Summary: Utility functions for AttackIQ Platform API usage
+License: MIT
+Author: Rajesh Sharma
+Author-email: rajesh.sharma@attackiq.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
+Description-Content-Type: text/markdown
+
+# AttackIQ Platform API Utilities
+
+⚠️ **BETA / WORK IN PROGRESS** ⚠️
+
+This package provides utility functions for interacting with the AttackIQ Platform API.
+
+## Status
+
+This project is currently in beta and under active development. Features and APIs may change without notice. Feedback and contributions are welcome!
+
+## Installation
+
+```bash
+pip install aiq-platform-api
+```
+
+## Examples
+
+To get started quickly with the example code:
+
+1. Copy the example files to your project:
+```bash
+cp examples/basic_usage.py your-project/
+cp examples/.env.example your-project/.env
+```
+
+2. Configure your credentials:
+```bash
+# Edit .env file with your AttackIQ Platform credentials
+vim .env
+```
+
+3. Install required packages:
+```bash
+pip install aiq-platform-api python-dotenv
+```
+
+4. Run the example:
+```bash
+python basic_usage.py
+```
+
+## Basic Usage
+
+```python
+from aiq_platform_api import assessment_use_cases
+
+assessment_use_cases.get_assessment_use_cases()
+```
+
+## Contributing
+
+We welcome feedback and contributions! Please feel free to:
+- Open issues for bugs or feature requests
+- Submit pull requests
+- Provide feedback on the API design
+
+## License
+
+MIT License - See LICENSE file for details

aiq_platform_api-0.1.1/README.md

@@ -0,0 +1,60 @@
+# AttackIQ Platform API Utilities
+
+⚠️ **BETA / WORK IN PROGRESS** ⚠️
+
+This package provides utility functions for interacting with the AttackIQ Platform API.
+
+## Status
+
+This project is currently in beta and under active development. Features and APIs may change without notice. Feedback and contributions are welcome!
+
+## Installation
+
+```bash
+pip install aiq-platform-api
+```
+
+## Examples
+
+To get started quickly with the example code:
+
+1. Copy the example files to your project:
+```bash
+cp examples/basic_usage.py your-project/
+cp examples/.env.example your-project/.env
+```
+
+2. Configure your credentials:
+```bash
+# Edit .env file with your AttackIQ Platform credentials
+vim .env
+```
+
+3. Install required packages:
+```bash
+pip install aiq-platform-api python-dotenv
+```
+
+4. Run the example:
+```bash
+python basic_usage.py
+```
+
+## Basic Usage
+
+```python
+from aiq_platform_api import assessment_use_cases
+
+assessment_use_cases.get_assessment_use_cases()
+```
+
+## Contributing
+
+We welcome feedback and contributions! Please feel free to:
+- Open issues for bugs or feature requests
+- Submit pull requests
+- Provide feedback on the API design
+
+## License
+
+MIT License - See LICENSE file for details

aiq_platform_api-0.1.1/aiq_platform_api/.env_template

@@ -0,0 +1,6 @@
+ATTACKIQ_PLATFORM_URL=https://firedrill.attackiq.com
+ATTACKIQ_API_TOKEN=
+ATTACKIQ_ASSESSMENT_ID=
+ATTACKIQ_ASSET_ID=
+ATTACKIQ_RESULT_SUMMARY_ID=
+JWT_TOKEN=

aiq_platform_api-0.1.1/aiq_platform_api/__init__.py

@@ -0,0 +1,28 @@
+"""AttackIQ Platform API Utilities
+
+This package provides utility functions for interacting with the AttackIQ Platform API.
+"""
+
+__version__ = "0.1.1"
+
+# Import all submodules to make them available when importing the package
+from . import assessment_use_cases
+from . import asset_use_cases
+from . import integration_use_cases
+from . import phase_log_use_cases
+from . import phase_results_use_cases
+from . import result_use_cases
+from . import tag_use_cases
+
+# Import key utilities from common_utils
+from .common_utils import (
+    AttackIQRestClient,
+    AssessmentUtils,
+    AssetUtils,
+    ResultsUtils,
+    TagUtils,
+    TaggedItemUtils,
+    PhaseResultsUtils,
+    PhaseLogsUtils,
+)
+

aiq_platform_api-0.1.1/aiq_platform_api/assessment_use_cases.py

@@ -0,0 +1,124 @@
+import itertools
+import os
+import time
+from typing import Optional
+
+from common_utils import AttackIQRestClient, AttackIQLogger, AssessmentUtils, AssetUtils
+from env import ATTACKIQ_API_TOKEN, ATTACKIQ_PLATFORM_URL
+
+logger = AttackIQLogger.get_logger(__name__)
+
+
+def list_assessments(client: AttackIQRestClient, limit: Optional[int] = None) -> int:
+    logger.info(f"Listing assessments (limit: {limit if limit else 'None'})...")
+    count = 0
+    assessments = AssessmentUtils.get_assessments(client)
+
+    for assessment in itertools.islice(assessments, limit):
+        count += 1
+        logger.info(f"Assessment {count}:")
+        logger.info(f"  ID: {assessment.get('id', 'N/A')}")
+        logger.info(f"  Name: {assessment.get('name', 'N/A')}")
+        logger.info(f"  Status: {assessment.get('status', 'N/A')}")
+        logger.info("---")
+
+    logger.info(f"Total assessments listed: {count}")
+    return count
+
+
+def get_assessment_results(
+    client: AttackIQRestClient, assessment_id: str, limit: Optional[int] = None
+):
+    logger.info(f"Fetching results for assessment ID: {assessment_id}")
+    results = AssessmentUtils.get_assessment_results(client, assessment_id)
+    for i, result in enumerate(itertools.islice(results, limit)):
+        logger.info(f"Result {i}:")
+        logger.info(f"  ID: {result.get('id', 'N/A')}")
+        logger.info(f"  Status: {result.get('status', 'N/A')}")
+        logger.info(f"  Start Time: {result.get('start_time', 'N/A')}")
+        logger.info(f"  End Time: {result.get('end_time', 'N/A')}")
+        logger.info("---")
+
+
+def run_assessment(client: AttackIQRestClient, assessment_id: str) -> Optional[str]:
+    logger.info(f"Running assessment with ID: {assessment_id}")
+    try:
+        run_id = AssessmentUtils.run_assessment(client, assessment_id)
+        logger.info(f"Assessment started successfully. Run ID: {run_id}")
+        return run_id
+    except Exception as e:
+        logger.error(f"Failed to run assessment: {str(e)}")
+        return None
+
+
+def wait_for_assessment_completion(
+    client: AttackIQRestClient,
+    assessment_id: str,
+    run_id: Optional[str] = None,
+    timeout: int = 600,
+    check_interval: int = 10,
+) -> bool:
+    start_time = time.time()
+    while time.time() - start_time < timeout:
+        if not AssessmentUtils.is_assessment_running(client, assessment_id):
+            elapsed_time = round(time.time() - start_time, 2)
+            logger.info(
+                f"Assessment {assessment_id} (Run ID: {run_id}) completed in {elapsed_time} seconds."
+            )
+            return True
+
+        if check_interval > 1:
+            logger.info(
+                f"Assessment {assessment_id} is still running. Waiting {check_interval} seconds..."
+            )
+        time.sleep(check_interval)
+
+    logger.warning(
+        f"Assessment {assessment_id} (Run ID: {run_id}) did not complete within {timeout} seconds."
+    )
+    return False
+
+
+def list_assets_in_assessment(
+    client: AttackIQRestClient, project_id: str, limit: Optional[int] = None
+):
+    logger.info(
+        f"Listing assets for project ID: {project_id} (limit: {limit if limit else 'None'})..."
+    )
+    params = {"hide_hosted_agents": "true", "project_id": project_id}
+    assets = AssetUtils.get_assets(client, params=params)
+    asset_count = 0
+    for asset in itertools.islice(assets, limit):
+        asset_count += 1
+        logger.info(f"Asset {asset_count}:")
+        logger.info(f"  ID: {asset.get('id', 'N/A')}")
+        logger.info(f"  Name: {asset.get('name', 'N/A')}")
+        logger.info(f"  Type: {asset.get('type', 'N/A')}")
+        logger.info(f"  IP Address: {asset.get('ipv4_address', 'N/A')}")
+        logger.info("---")
+    logger.info(f"Total assets listed: {asset_count}")
+    return asset_count
+
+
+def main():
+    client = AttackIQRestClient(ATTACKIQ_PLATFORM_URL, ATTACKIQ_API_TOKEN)
+    assessment_id = os.environ.get("ATTACKIQ_ASSESSMENT_ID")
+
+    list_assessments(client, limit=5)
+
+    if assessment_id:
+        list_assets_in_assessment(client, assessment_id, limit=5)
+        get_assessment_results(client, assessment_id, limit=5)
+        run_id = run_assessment(client, assessment_id)
+        if run_id:
+            wait_for_assessment_completion(
+                client, assessment_id, run_id, timeout=20, check_interval=1
+            )
+    else:
+        logger.warning(
+            "ATTACKIQ_ASSESSMENT_ID environment variable is not set. Skipping assessment-specific operations."
+        )
+
+
+if __name__ == "__main__":
+    main()

aiq_platform_api-0.1.1/aiq_platform_api/asset_use_cases.py

@@ -0,0 +1,167 @@
+import itertools
+import os
+
+from common_utils import (
+    AttackIQRestClient,
+    AttackIQLogger,
+    AssetUtils,
+    TagUtils,
+    TaggedItemUtils,
+    AssetStatus,
+)
+from env import ATTACKIQ_API_TOKEN, ATTACKIQ_PLATFORM_URL
+
+logger = AttackIQLogger.get_logger(__name__)
+
+
+def fetch_and_log_assets(client: AttackIQRestClient, limit: int):
+    logger.info(f"Fetching and processing assets with limit {limit}...")
+    asset_count = 0
+    assets = AssetUtils.get_assets(client)
+
+    for asset in itertools.islice(assets, limit):
+        asset_count += 1
+        logger.info(f"Asset {asset_count}:")
+        logger.info(f"  ID: {asset.get('id')}")
+        logger.info(f"  Name: {asset.get('name')}")
+        logger.info(f"  Type: {asset.get('type')}")
+        logger.info(f"  IP Address: {asset.get('ipv4_address')}")
+        logger.info("---")
+
+    if asset_count == 0:
+        logger.error("Failed to retrieve any assets.")
+    else:
+        logger.info(f"Successfully processed {asset_count} assets.")
+
+
+def find_asset_by_hostname(client: AttackIQRestClient, hostname: str):
+    logger.info(f"Searching for asset with hostname: {hostname}")
+    asset = AssetUtils.get_asset_by_hostname(client, hostname)
+
+    if asset:
+        logger.info("Asset found:")
+        logger.info(f"  ID: {asset.get('id')}")
+        logger.info(f"  Name: {asset.get('name')}")
+        logger.info(f"  Type: {asset.get('type')}")
+        logger.info(f"  IP Address: {asset.get('ipv4_address')}")
+        logger.info(f"  Hostname: {asset.get('hostname')}")
+    else:
+        logger.info(f"No asset found with hostname: {hostname}")
+
+
+def uninstall_asset_by_uuid(client: AttackIQRestClient, asset_id: str):
+    if not asset_id:
+        logger.error("Asset id not provided.")
+        return
+
+    asset = AssetUtils.get_asset_by_id(client, asset_id)
+    if not asset:
+        logger.error(f"Asset with id {asset_id} not found.")
+        return
+
+    logger.info(f"Attempting to uninstall asset with id: {asset_id}")
+    success = AssetUtils.uninstall_asset(client, asset_id)
+
+    if success:
+        logger.info(f"Asset {asset_id} uninstall job submitted successfully.")
+    else:
+        logger.error(f"Failed to submit uninstall job for asset {asset_id}.")
+
+
+def list_asset_tags(client: AttackIQRestClient, asset_id: str, limit: int):
+    logger.info(f"Listing tags for asset with ID: {asset_id}")
+    tag_count = 0
+    tagged_items = TaggedItemUtils.get_tagged_items(client, "asset", asset_id)
+    for tagged_item in itertools.islice(tagged_items, limit):
+        tag_count += 1
+        tag_id = tagged_item.get("tag_id")
+        logger.info(f"Tagged Item {tag_count}:")
+        logger.info(f"  ID: {tagged_item.get('id')}")
+        logger.info(f"  Tag ID: {tag_id}")
+    logger.info(f"Total tags listed: {tag_count}")
+
+
+def tag_asset(client: AttackIQRestClient, asset_id: str, tag_id: str) -> str:
+    logger.info(f"Tagging asset with ID: {asset_id} with tag ID: {tag_id}")
+    tagged_item = TaggedItemUtils.get_tagged_item(client, "asset", asset_id, tag_id)
+    tagged_item_id = tagged_item.get("id") if tagged_item else ""
+    if tagged_item_id:
+        logger.info(
+            f"Asset {asset_id} is already tagged with tag item ID {tagged_item_id}"
+        )
+        return tagged_item_id
+    tagged_item_id = AssetUtils.add_tag(client, asset_id, tag_id)
+    if tagged_item_id:
+        logger.info(
+            f"Successfully tagged asset {asset_id} with tag item ID {tagged_item_id}"
+        )
+        return tagged_item_id
+    else:
+        logger.error(f"Failed to tag asset {asset_id} with tag ID {tag_id}")
+        return ""
+
+
+def untag_asset(client: AttackIQRestClient, tagged_item_id: str):
+    logger.info(f"Removing tag item with ID: {tagged_item_id}")
+    success = TaggedItemUtils.delete_tagged_item(client, tagged_item_id)
+    if success:
+        logger.info(f"Successfully removed tag item with ID {tagged_item_id}")
+    else:
+        logger.error(f"Failed to remove tag item with ID {tagged_item_id}")
+
+
+def delete_tag(client: AttackIQRestClient, tag_id: str) -> bool:
+    logger.info(f"Deleting tag with ID: {tag_id}")
+    success = TagUtils.delete_tag(client, tag_id)
+    if success:
+        logger.info(f"Successfully deleted tag with ID {tag_id}")
+    else:
+        logger.error(f"Failed to delete tag with ID {tag_id}")
+    return success
+
+
+def get_and_log_total_assets(client: AttackIQRestClient):
+    total_assets = AssetUtils.get_total_assets(client)
+    if total_assets is not None:
+        logger.info(f"Total number of assets: {total_assets}")
+    else:
+        logger.error("Failed to retrieve total number of assets.")
+
+
+def get_and_log_assets_count_by_status(client: AttackIQRestClient, status: AssetStatus):
+    assets_count = AssetUtils.get_assets_count_by_status(client, status)
+    if assets_count is not None:
+        logger.info(f"Number of {status.value} assets: {assets_count}")
+    else:
+        logger.error(f"Failed to retrieve count of {status.value} assets.")
+
+
+def main():
+    client = AttackIQRestClient(ATTACKIQ_PLATFORM_URL, ATTACKIQ_API_TOKEN)
+
+    get_and_log_total_assets(client)
+    get_and_log_assets_count_by_status(client, AssetStatus.ACTIVE)
+    get_and_log_assets_count_by_status(client, AssetStatus.INACTIVE)
+
+    fetch_and_log_assets(client, limit=25)
+    find_asset_by_hostname(client, "AIQ-CY4C7CC9W5")
+
+    asset_id = os.environ.get("ATTACKIQ_ASSET_ID")
+    if asset_id:
+        if AssetUtils.get_asset_by_id(client, asset_id):
+            tag_name = "TEST_TAG"
+            if tag_id := TagUtils.get_or_create_custom_tag(client, tag_name):
+                logger.info(f"Tag ID: {tag_id} for tag '{tag_name}'")
+                if tagged_item_id := tag_asset(client, asset_id, tag_id):
+                    list_asset_tags(client, asset_id, limit=5)
+                    untag_asset(client, tagged_item_id)
+                    delete_tag(client, tag_id)
+                uninstall_asset_by_uuid(client, asset_id)
+    else:
+        logger.warning(
+            "ATTACKIQ_ASSET_UUID environment variable is not set. Skipping asset-specific operations."
+        )
+
+
+if __name__ == "__main__":
+    main()