illumio-pylo 0.3.11__tar.gz → 0.3.13__tar.gz

{illumio_pylo-0.3.11 → illumio_pylo-0.3.13}/.github/workflows/make-binaries.yml

@@ -20,6 +20,7 @@ jobs:
       - name: Change Pylo Version if this is a DEV build
         if: github.ref == 'refs/heads/dev' && github.event_name == 'push'
         run: |
+          pwd
           echo "Update version to append '-dev-' and current date ISO format:"
           # for double quoted strings version
           sed -i -E "s/__version__ = \"([0-9]+\.[0-9]+\.[0-9]+)\"/__version__ = '\\1-dev-$(date +'%Y%m%d')'/" illumio_pylo/__init__.py
@@ -28,12 +29,49 @@ jobs:
           grep __version__ illumio_pylo/__init__.py
           
 
+      - name: copy scripts and pkg to build folder
+        run: |
+          # build the package
+          pip install build
+          python -m build
+          echo "current working directory:"
+          pwd
+          # get package whl filename for later use, it is in dist/
+          package_filename=$(find dist/ -name "illumio_pylo-*.whl" | sed 's|dist/||')
+          echo "*** Package filename is: $package_filename"
+          mkdir cli-build
+          # move package to cli-build
+          mv "dist/$package_filename" cli-build/
+          
+          # create requirements.txt that points to the local package
+          echo "illumio_pylo@file:./cli-build/$package_filename" > cli-build/requirements.txt
+          #echo "pyinstaller==6.16.0" >> cli-build/requirements.txt
+          echo "*** Created cli-build/requirements.txt with contents:"
+          cat cli-build/requirements.txt
+          
+          # copy cli.py removing any sys.path.insert lines
+          grep -v 'sys.path.insert' illumio_pylo/utilities/cli.py > cli-build/cli.py
+          mv illumio_pylo/utilities/health_monitoring.py cli-build/
+          
+          # delete illumio_pylo to avoid confusion
+          rm -rf illumio_pylo/
+          
+          echo "*** Contents of cli-build/:"
+          find cli-build/
+
       - name: Make executables
         uses: cpainchaud/pyinstaller-action-windows@main
         with:
           path: ./
-          spec: illumio_pylo/utilities/
-          extra_python_paths: Z:\\github\\workspace\\;Z:\\github\\workspace\\pylo;C:\\Windows\\System32\\downlevel
+          spec: ./cli-build/
+          requirements: ./cli-build/requirements.txt
+          collect_data: illumio_pylo
+          extra_python_paths: Z:\\github\\workspace\\;C:\\Windows\\System32\\downlevel
+
+      - name: show spec files
+        run: |
+          echo "Showing the spec files created by PyInstaller:"
+          find ../ -name "*.spec" -exec cat {} \;
 
       - name: rename executables
         run: |

{illumio_pylo-0.3.11/illumio_pylo.egg-info → illumio_pylo-0.3.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: illumio_pylo
-Version: 0.3.11
+Version: 0.3.13
 Summary: A set of tools and library for working with Illumio PCE
 Home-page: https://github.com/cpainchaud/pylo
 Author: Christophe Painchaud
@@ -193,6 +193,7 @@ Requires-Dist: paramiko~=3.4.0
 Requires-Dist: prettytable~=3.10.0
 Requires-Dist: requests~=2.32.0
 Requires-Dist: xlsxwriter~=3.2.0
+Requires-Dist: flask~=2.2.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: description

illumio_pylo-0.3.13/docs/ENV_CREDENTIALS.md

@@ -0,0 +1,205 @@
+# Environment Variable Credentials
+
+## Overview
+
+The `CredentialProfile.from_environment_variables()` feature allows you to provide Illumio PCE credentials via environment variables instead of storing them in credential files on disk. This is particularly useful for:
+
+- CI/CD pipelines
+- Docker containers
+- Security-conscious environments where credentials shouldn't be written to disk
+- Temporary credential usage
+
+## Usage
+
+To use environment variable credentials, simply specify the profile name `'ENV'` (case-insensitive) when loading credentials:
+
+```python
+import illumio_pylo as pylo
+
+# Load credentials from environment variables
+credentials = pylo.get_credentials_from_file('ENV')
+
+# Or use with APIConnector
+connector = pylo.APIConnector.create_from_credentials_in_file('ENV')
+
+# Or use with Organization
+org = pylo.Organization.get_from_api_using_credential_file('ENV')
+```
+
+## Required Environment Variables
+
+- **`PYLO_FQDN`**: Fully qualified domain name of the PCE (e.g., `pce.example.com`)
+- **`PYLO_API_USER`**: API username
+- **`PYLO_API_KEY`**: API key (can be encrypted with `$encrypted$:` prefix)
+
+## Optional Environment Variables
+
+- **`PYLO_PORT`**: Port number
+  - Default: `8443` for standard PCE
+  - Default: `443` for illum.io hosted domains (SaaS)
+  - Valid range: 1-65535
+
+- **`PYLO_ORG_ID`**: Organization ID
+  - Default: `1` for standard PCE
+  - **Required** for illum.io hosted domains (no default)
+  - Must be a positive integer
+
+- **`PYLO_VERIFY_SSL`**: Verify SSL certificate
+  - Default: `true`
+  - Accepts: `true`, `false`, `1`, `0`, `yes`, `no`, `y`, `n` (case-insensitive)
+
+## Examples
+
+### Basic Example (Standard PCE)
+
+```bash
+# Set environment variables
+export PYLO_FQDN="pce.example.com"
+export PYLO_API_USER="api_12345"
+export PYLO_API_KEY="your_api_key_here"
+
+# Run your Python script
+python your_script.py
+```
+
+```python
+import illumio_pylo as pylo
+
+# Load from environment
+org = pylo.Organization.get_from_api_using_credential_file('ENV')
+print(f"Connected to {org.connector.fqdn}")
+```
+
+### Illumio SaaS Example
+
+```bash
+# For illum.io domains, ORG_ID is required
+export PYLO_FQDN="mycompany.illum.io"
+export PYLO_API_USER="api_12345"
+export PYLO_API_KEY="your_api_key_here"
+export PYLO_ORG_ID="5"
+
+# Port defaults to 443 for illum.io domains
+python your_script.py
+```
+
+### Custom Configuration
+
+```bash
+# Custom port and disable SSL verification
+export PYLO_FQDN="pce.internal.local"
+export PYLO_API_USER="api_12345"
+export PYLO_API_KEY="your_api_key_here"
+export PYLO_PORT="9443"
+export PYLO_ORG_ID="2"
+export PYLO_VERIFY_SSL="false"
+
+python your_script.py
+```
+
+### Docker Container Example
+
+```bash
+docker run -e PYLO_FQDN="pce.example.com" \
+           -e PYLO_API_USER="api_12345" \
+           -e PYLO_API_KEY="your_api_key" \
+           your-container:latest
+```
+
+### Encrypted API Key
+
+If you have an encrypted API key (generated with the `cred-manager` tool), you can use it directly:
+
+```bash
+export PYLO_FQDN="pce.example.com"
+export PYLO_API_USER="api_12345"
+export PYLO_API_KEY='$encrypted$:ssh-ChaCha20Poly1305:...'
+
+python your_script.py
+```
+
+The API key will be automatically decrypted using your SSH agent.
+
+## Checking Availability
+
+You can check if required environment variables are set before attempting to load:
+
+```python
+from illumio_pylo.API.CredentialsManager import is_env_credentials_available
+
+if is_env_credentials_available():
+    print("Environment credentials are available")
+    credentials = pylo.get_credentials_from_file('ENV')
+else:
+    print("Missing required environment variables")
+    # Fall back to file-based credentials
+    credentials = pylo.get_credentials_from_file('default')
+```
+
+## Validation and Error Handling
+
+The implementation includes comprehensive validation:
+
+- **Missing required variables**: Clear error message listing which variables are missing
+- **Invalid port**: Must be a valid integer between 1-65535
+- **Invalid org_id**: Must be a positive integer
+- **Invalid verify_ssl**: Must be a boolean-like value
+- **illum.io domains**: Automatically defaults port to 443 and requires ORG_ID
+
+Example error messages:
+
+```
+Missing required environment variables for ENV profile: PYLO_FQDN, PYLO_API_KEY.
+Required: PYLO_FQDN, PYLO_API_USER, PYLO_API_KEY.
+Optional: PYLO_PORT, PYLO_ORG_ID, PYLO_VERIFY_SSL
+
+Invalid PYLO_PORT value 'abc': must be a valid port number (1-65535)
+
+PYLO_ORG_ID is required for illum.io domains (no default available)
+
+Invalid PYLO_VERIFY_SSL value 'maybe': must be true/false/1/0/yes/no/y/n (case-insensitive)
+```
+
+## Security Considerations
+
+### Advantages
+- Credentials never written to disk
+- Easier to rotate in CI/CD environments
+- No risk of accidentally committing credentials to version control
+- Better integration with secrets management tools (AWS Secrets Manager, HashiCorp Vault, etc.)
+
+### Best Practices
+1. **Never log environment variables** - Be careful not to print or log the actual API key
+2. **Use encrypted keys when possible** - Leverage SSH agent encryption for additional security
+3. **Rotate credentials regularly** - Environment-based approach makes rotation easier
+4. **Use secrets management** - In production, use proper secrets management tools to inject environment variables
+5. **Limit scope** - Set environment variables only for the specific process that needs them
+
+### Example with AWS Secrets Manager
+
+```python
+import boto3
+import json
+import os
+import illumio_pylo as pylo
+
+# Fetch credentials from AWS Secrets Manager
+client = boto3.client('secretsmanager')
+secret = client.get_secret_value(SecretId='pylo/pce/credentials')
+creds = json.loads(secret['SecretString'])
+
+# Set environment variables
+os.environ['PYLO_FQDN'] = creds['fqdn']
+os.environ['PYLO_API_USER'] = creds['api_user']
+os.environ['PYLO_API_KEY'] = creds['api_key']
+
+# Use ENV profile
+org = pylo.Organization.get_from_api_using_credential_file('ENV')
+```
+
+## Notes
+
+- The profile name is always `'ENV'` (case-insensitive: `'env'`, `'Env'`, `'ENV'` all work)
+- The `originating_file` attribute is set to `'environment'` for env-based profiles
+- Environment credentials are **never** included in `get_all_credentials()` - they must be explicitly requested
+- Environment credentials don't require any credential files to exist on disk

illumio_pylo-0.3.13/examples/example_env_credentials.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""
+Practical example of using environment variable credentials with Illumio Pylo
+This demonstrates how to connect to a PCE using only environment variables
+"""
+import os
+import illumio_pylo as pylo
+
+def main():
+    # Check if environment credentials are available
+    from illumio_pylo.API.CredentialsManager import is_env_credentials_available
+
+    if not is_env_credentials_available():
+        print("ERROR: Required environment variables are not set!")
+        print("Please set: PYLO_FQDN, PYLO_API_USER, PYLO_API_KEY")
+        print("\nExample:")
+        print("  export PYLO_FQDN='pce.example.com'")
+        print("  export PYLO_API_USER='api_12345'")
+        print("  export PYLO_API_KEY='your_api_key_here'")
+        return 1
+
+    print("Environment credentials detected!")
+    print("-" * 60)
+
+    # Load credentials from environment
+    try:
+        credentials = pylo.get_credentials_from_file('ENV')
+        print(f"Credentials loaded:")
+        print(f"  FQDN: {credentials.fqdn}")
+        print(f"  Port: {credentials.port}")
+        print(f"  Org ID: {credentials.org_id}")
+        print(f"  API User: {credentials.api_user}")
+        print(f"  Verify SSL: {credentials.verify_ssl}")
+        print(f"  Source: {credentials.originating_file}")
+        print("-" * 60)
+    except pylo.PyloEx as e:
+        print(f"ERROR loading credentials: {e}")
+        return 1
+
+    # Example 1: Create an APIConnector
+    print("\nExample 1: Creating APIConnector from ENV profile")
+    try:
+        connector = pylo.APIConnector.create_from_credentials_in_file('ENV')
+        print(f"✓ APIConnector created for {connector.fqdn}:{connector.port}")
+
+        # Test connection by getting software version
+        version = connector.get_software_version()
+        print(f"✓ Connected successfully! PCE Version: {version}")
+
+    except Exception as e:
+        print(f"✗ Connection failed: {e}")
+        print("  (This is expected if the PCE is not accessible)")
+
+    # Example 2: Load Organization data
+    print("\nExample 2: Loading Organization from ENV profile")
+    try:
+        org = pylo.Organization.get_from_api_using_credential_file(
+            'ENV',
+            list_of_objects_to_load=[
+                pylo.ObjectTypes.LABEL,
+                pylo.ObjectTypes.WORKLOAD
+            ]
+        )
+        print(f"✓ Organization loaded successfully!")
+        print(f"  Labels: {len(org.LabelStore.itemsByHref)}")
+        print(f"  Workloads: {len(org.WorkloadStore.itemsByHref)}")
+
+    except Exception as e:
+        print(f"✗ Failed to load organization: {e}")
+        print("  (This is expected if the PCE is not accessible)")
+
+    print("\n" + "=" * 60)
+    print("Example complete!")
+    return 0
+
+if __name__ == '__main__':
+    exit(main())

illumio_pylo-0.3.13/examples/explorer_query.py

@@ -0,0 +1,101 @@
+"""
+In this example we will show how to query traffic logs from the PCE using the Explorer V2 APIs.
+We will make a query for all traffic logs matching the following conditions:
+- Source (consumer) has a label 'E-PRODUCTION' or 'E-PREPROD' or is part of IPList 'I-Prod-Networks'
+- Destination (provider) can be any workload or IP
+- Service is TCP port 80 or 443 or ICMP protocol
+- Policy decision is 'allowed'
+- Traffic was detected within the last 5 days
+"""
+
+import os
+import sys
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.realpath(__file__))))  # only required if you run this script from the examples folder without installing pylo
+import illumio_pylo as pylo
+
+# PCE connection parameters
+pce_hostname = 'pce1.company.com'
+pce_port = 9443
+pce_api_user = 'api_xxxxxxxxx'
+pce_api_key = 'xxxxxxxxxxxxxxxxxxxx'
+pce_org_id = 1
+pce_verify_ssl = True
+
+print("Loading organization from PCE '{}'... ".format(pce_hostname), end='', flush=True)
+organization = pylo.get_organization(pce_hostname, pce_port, pce_api_user, pce_api_key, pce_org_id, pce_verify_ssl)
+print("OK!")
+
+# Create a new V2 Explorer query with a max of 1500 results
+explorer_query = organization.connector.new_explorer_query_v2(max_results=1500)
+
+# Define source filter criteria
+source_labels_names = ['E-PRODUCTION', 'E-PREPROD']
+source_ip_list_name = 'I-Prod-Networks'
+
+# Create a source filter that combines labels and IPList (treated with OR logic)
+source_filter = explorer_query.filters.new_source_filter()
+
+# Lookup and add Label objects to the source filter
+for label_name in source_labels_names:
+    label_search_result = organization.LabelStore.find_label_by_name(label_name, raise_exception_if_not_found=False, case_sensitive=False)
+    if len(label_search_result) == 0:
+        raise pylo.PyloEx("Label '{}' not found in PCE!".format(label_name))
+    elif len(label_search_result) > 1:
+        raise pylo.PyloEx("Multiple labels found for name '{}', please use a more specific name!".format(label_name))
+    source_filter.add_label(label_search_result[0])
+
+# Lookup and add IPList object to the source filter
+source_iplist = organization.IPListStore.find_by_name(source_ip_list_name)
+if source_iplist is None:
+    raise pylo.PyloEx("IPList '{}' not found in PCE!".format(source_ip_list_name))
+source_filter.add_iplist(source_iplist)
+
+# Filter by services (ICMP, HTTP, HTTPS)
+explorer_query.filters.service_include_add_protocol(1)  # ICMP
+explorer_query.filters.service_include_add('tcp/80')  # HTTP
+explorer_query.filters.service_include_add('tcp/443')  # HTTPS
+
+# Filter by policy decision (only allowed traffic)
+explorer_query.filters.filter_on_policy_decision_allowed()
+
+# Filter by time range (last 5 days)
+explorer_query.filters.set_time_from_x_days_ago(5)
+
+# Execute the query and retrieve traffic logs
+print("Querying PCE for traffic logs matching the filter... ", end='', flush=True)
+traffic_logs = explorer_query.execute()
+records = traffic_logs.get_all_records()
+print("OK! Found {} traffic log(s)".format(len(records)))
+
+# Print the results
+for record in records:
+    # Format source information
+    if record.source_is_workload():
+        workload = record.get_source_workload(organization)
+        # Get labels as a formatted string
+        label_values = [record.source_workload_labels_by_type.get(lt) for lt in organization.LabelStore.label_types]
+        label_values = [lv for lv in label_values if lv is not None]
+        labels_str = '|'.join(label_values) if label_values else 'unlabeled'
+        consumer_text = "Workload '{}' ({})".format(workload.name if workload else record.source_workload_hostname, labels_str)
+    else:
+        consumer_text = "IP '{}'".format(record.source_ip)
+
+    # Format destination information
+    if record.destination_is_workload():
+        workload = record.get_destination_workload(organization)
+        # Get labels as a formatted string
+        label_values = [record.destination_workload_labels_by_type.get(lt) for lt in organization.LabelStore.label_types]
+        label_values = [lv for lv in label_values if lv is not None]
+        labels_str = '|'.join(label_values) if label_values else 'unlabeled'
+        provider_text = "Workload '{}' ({})".format(workload.name if workload else record.destination_workload_hostname, labels_str)
+    else:
+        provider_text = "IP '{}'".format(record.destination_ip)
+
+    # Format service information
+    service_text = record.service_to_str()
+
+    # Print the traffic log entry
+    print("Traffic log: {} -> {} via {} (policy decision: {})".format(
+        consumer_text, provider_text, service_text, record.policy_decision_string))
+

{illumio_pylo-0.3.11 → illumio_pylo-0.3.13}/examples/extend_cli.py

@@ -23,6 +23,7 @@ class MyBuiltInParser:  # optional, if you want to use built-in parsers
                                    label_type='env',  # optional, it will ensure that selected labels are of a specified type
                                    is_required=False, allow_multiple=True)
 
+
 def fill_parser(parser: argparse.ArgumentParser):
     """ This function will be called by the CLI to fill the parser with the arguments of your command """
     parser.add_argument('--sort-by-name', '-s', action='store_true',

illumio_pylo-0.3.13/examples/filter_query_example.py

@@ -0,0 +1,122 @@
+"""
+Example: Using the Filter Query feature to search workloads
+
+This example demonstrates how to use the find_workloads_matching_query() method
+to filter workloads using a SQL-like query syntax.
+"""
+
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.realpath(__file__))))
+
+import illumio_pylo as pylo
+
+
+def main():
+    # Load organization from PCE (using credentials file or cached data)
+    # Replace 'your-pce-hostname' with your actual PCE hostname
+    pce_hostname = 'your-pce-hostname'
+
+    print(f"Loading PCE configuration from {pce_hostname}...")
+    org = pylo.Organization(1)
+
+    # Option 1: Load from API using saved credentials
+    # org.load_from_api_using_credential_file(pce_hostname)
+
+    # Option 2: Load from cache (if you've previously cached the data)
+    try:
+        org.load_from_cache_or_saved_credentials(pce_hostname)
+    except Exception as e:
+        print(f"Failed to load PCE data: {e}")
+        print("\nTo use this example, you need to either:")
+        print("  1. Configure credentials in ~/.pylo/credentials.json")
+        print("  2. Have cached PCE data available")
+        return
+
+    print(f"Loaded {len(org.WorkloadStore.workloads)} workloads from PCE\n")
+
+    # Example queries
+    example_queries = [
+        # Find workloads by name
+        "name == 'web-server-01'",
+
+        # Find workloads by partial name match
+        "name contains 'web'",
+
+        # Find workloads by name using regex
+        "name matches 'web-.*-[0-9]+'",
+
+        # Find workloads by IP address
+        "ip_address == '192.168.1.100'",
+
+        # Find online workloads
+        "online == true",
+
+        # Find workloads by label
+        "env == 'Production'",
+        "label.app == 'WebApp' and label.env == 'Production'",
+
+        # Complex query with OR
+        "(name == 'server-01' or name == 'server-02') and online == true",
+
+        # Find workloads with old heartbeat
+        "last_heartbeat <= '2024-01-01'",
+
+        # Find workloads in a specific mode
+        "mode == 'enforced'",
+
+        # Find deleted workloads (need to pass include_deleted=True)
+        "deleted == true",
+
+        # Combine multiple conditions
+        "hostname contains 'prod' and env == 'Production' and not deleted == true",
+    ]
+
+    print("=" * 60)
+    print("Filter Query Examples")
+    print("=" * 60)
+
+    for query in example_queries:
+        print(f"\nQuery: {query}")
+        try:
+            results = org.WorkloadStore.find_workloads_matching_query(query)
+            print(f"Found {len(results)} workload(s)")
+            for wkl in results[:5]:  # Show first 5 results
+                print(f"  - {wkl.get_name()} ({wkl.href})")
+            if len(results) > 5:
+                print(f"  ... and {len(results) - 5} more")
+        except pylo.PyloEx as e:
+            print(f"Error: {e}")
+
+    # Interactive query mode
+    print("\n" + "=" * 60)
+    print("Interactive Query Mode")
+    print("Enter a query to search workloads, or 'quit' to exit")
+    print("=" * 60)
+
+    while True:
+        try:
+            query = input("\nQuery> ").strip()
+            if query.lower() in ('quit', 'exit', 'q'):
+                break
+            if not query:
+                continue
+
+            results = org.WorkloadStore.find_workloads_matching_query(query)
+            print(f"Found {len(results)} workload(s)")
+            for wkl in results[:10]:
+                labels = wkl.get_labels_str()
+                print(f"  - {wkl.get_name()} | {labels} | online={wkl.online}")
+            if len(results) > 10:
+                print(f"  ... and {len(results) - 10} more")
+        except pylo.PyloEx as e:
+            print(f"Query error: {e}")
+        except KeyboardInterrupt:
+            break
+
+    print("\nGoodbye!")
+
+
+if __name__ == '__main__':
+    main()