maxpower86/psm-buddy repository overview

⁠PSM Buddy - Network Flow Analysis & PSM Object Management

It accelerates the journey to network (micro-) segmentation by creating network and security policy related objects.

⁠🚀 Key Features

⁠Core Functionality

• Switch Integration: Direct integration with Aruba CX 10000 via REST API for VRF/VLAN creation on PSM
• Network Flow Analysis: Extract and analyze network flow data from Elasticsearch syslog indices
• Policy Management: Create and manage IP collections, applications, VRFs, and VLANs in PSM
• DNS Resolution: Background DNS hostname resolution (in case logstash provides no DNS RR)
• Port Mapping: Customizable protocol-port-to-application mappings for traffic classification
• PSM Snapshots: Scheduled and encrypted PSM snapshots, with mutli-destination (SCP, SFTP, folder) and retention control

⁠Advanced Features

• PSM-CXOS Compatibility Checking: Automatic detection and warnings for major versions incompatibilities
• Auto-Connect: Automatically restore Elasticsearch and PSM connections on login
• Dark Mode Support: Full dark/light theme toggle with system preference detection
• Toast Notifications: Real-time user feedback system
• Health Monitoring: Built-in health checks and comprehensive logging

⁠Compatibility System

PSM Buddy includes an intelligent compatibility checking system that:

• Detects PSM and CXOS versions automatically
• Compares against known compatibility matrices
• Displays prominent warnings for major incompatibilities
• Applies certain features only for compatible versions

⁠📋 Quick Start

⁠Option 1: Integration with AMD Pensando ELK Stack*

If you're using the AMD Pensando ELK stack⁠, add this service to your existing docker-compose.yml:

  psm-buddy:
    image: maxpower86/psm-buddy:latest
    container_name: psm-buddy
    ports:
      - "5600:5600"
    environment:
      # Enable TLS (Optional)
      - TLS_ENABLED=False
    volumes:
      # Persist application configuration files
      - ${PWD}/psmbuddy/app-instance:/app/var/app-instance
      # Persist snapshots and logs
      - ${PWD}/psmbuddy/snapshot/logs:/var/log/pensando/snapshot
      - ${PWD}/psmbuddy/snapshot:/app/snapshot
      # Shared APPID file with Logstash
      - ${PWD}/logstash/prot_port_to_app_mapping.yml:/app/var/app-instance/prot_port_to_app_mapping.yml
      # TLS Certificate and Key (optional)
      # - ${PWD}/psmbuddy/psm-buddy-cert.pem:/app/certs/cert.pem
      # - ${PWD}/psmbuddy/psm-buddy-key.pem:/app/certs/key.pem
    healthcheck:
      test: ["CMD", "/usr/local/bin/healthcheck.sh"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    restart: unless-stopped
    networks: ['elk-stack']

volumes:
  psm-buddy-config:
    driver: local
  psm-buddy-logs:
    driver: local

⁠Option 2: Standalone Installation**

For a standalone PSM Buddy deployment, create a new docker-compose.yml:

name: psm-buddy

services:
  psm-buddy:
    image: maxpower86/psm-buddy:latest
    container_name: psm-buddy
    ports:
      - "5600:5600"
    environment:
      - TLS_ENABLED=False
    volumes:
      # Persist application configuration files
      - ${PWD}/psmbuddy/app-instance:/app/var/app-instance
      # Persist snapshots and logs
      - ${PWD}/psmbuddy/snapshot/logs:/var/log/pensando/snapshot
      - ${PWD}/psmbuddy/snapshot:/app/snapshot
      # TLS Certificate and Key (optional)
      # - ${PWD}/psmbuddy/psm-buddy-cert.pem:/app/certs/cert.pem
      # - ${PWD}/psmbuddy/psm-buddy-key.pem:/app/certs/key.pem
    healthcheck:
      test: ["CMD", "/usr/local/bin/healthcheck.sh"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    restart: unless-stopped
    networks:
      - psm-buddy-network
    
networks:
  psm-buddy-network:
    driver: bridge

volumes:
  psm-buddy-config:
    driver: local
  psm-buddy-logs:
    driver: local

Start the application:

docker compose up -d

Access PSM Buddy:

• Open your browser to https://localhost:5600
• Default credentials: admin / Pensando0$

⁠⚙️ Configuration Options

⁠TLS/SSL Configuration

⁠Authentication

Note: Most configuration (Elasticsearch, PSM, DNS servers, switch credentials) is managed through the web UI after login.

⁠🌐 Network Requirements

⁠Port and Protocol Requirements

PSM Buddy requires the following network connectivity:

⁠Firewall Considerations

Ensure your firewall rules allow:

• Inbound: Port 5600 (TCP) for web access
• Outbound: All ports listed above for respective services

⁠📂 Volume Mounts

⁠Required Volumes

• Configuration Persistence: /app/var/app-instance

  • Stores connection settings, user preferences, and application state
  • Uses Docker managed volume for easy backup/restore

• Snapshots: /app/snapshot

  • Local storage for PSM snapshots

• Backup Logs: /var/log/pensando/snapshot

  • Stores PSM backup operation logs
  • Important for audit trails and troubleshooting

⁠Optional Volumes

• SSL Certificates: /app/certs

  • Mount your SSL certificates for HTTPS support
  • Requires TLS_ENABLED=True

• Port Mappings: /app/var/app-instance/prot_port_to_app_mapping.yml

  • Custom port-to-application mappings for Logstash integration
  • Format: "port_protocol": "Application Name"

⁠🔒 Security Considerations

⁠Production Deployment

1. Change Default Credentials: Always override ADMIN_USERNAME and ADMIN_PASSWORD
2. Enable TLS: Use TLS_ENABLED=True with valid certificates
3. Certificate Security: Use trusted certificates from a CA for production
4. Log Management: Implement log rotation and centralized logging

⁠📸 Application Screenshots

⁠1. Status Dashboard

⁠2. Networking

⁠3. IP Collections

⁠4. Applications

⁠6. PSM Backups

⁠📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Note: PSM Buddy is designed for network administrators working with Pensando infrastructure. Ensure you have proper network access and credentials for your Elasticsearch and PSM instances before deployment.

* AMD ELK Integration: When used with the AMD Pensando ELK stack, PSM Buddy automatically shares port mappings with Logstash and provides the creation of IP Collections and APPS based on the gathered telemetry information.

** Standalone Deployment: The standalone version provides all core functionality without the object creation based on the telemetry gathered by ELK.