mindfabric-agent 1.1.357

MindFabric AI Agent - Universal Infrastructure Orchestrator

MindFabric Agent

MindFabric AI Agent - Universal Infrastructure Orchestrator

Description

MindFabric Agent is a powerful AI-driven infrastructure orchestration tool that provides automated management, monitoring, and optimization for various IT environments. It supports multiple platforms including Kubernetes, Docker, cloud services, and traditional infrastructure.

Features

• Universal Infrastructure Support: Works with Kubernetes, Docker, AWS, Azure, GCP, and traditional servers
• Plugin Architecture: Extensible plugin system for custom functionality
• Real-time Monitoring: WebSocket-based real-time monitoring and control
• Database Integration: Support for PostgreSQL, MySQL, SQLite, and other databases
• Security Scanning: Built-in security and vulnerability scanning capabilities
• Network Discovery: Automated network mapping and discovery
• OSINT Integration: Open source intelligence gathering capabilities
• Docker Escape Detection: Advanced container security analysis

Installation

From TestPyPI (Beta Version)

pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ mindfabric-agent

From PyPI (Stable Version)

pip install mindfabric-agent

Quick Start

Option 1: Run as Command (Simple)

# Install from TestPyPI (with dependencies from main PyPI)
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ mindfabric-agent

# Run with environment variables (minimal setup - ACCESS_KEY is required!)
ACCESS_KEY=your-key mindfabric-agent

# With custom agent name and backend URL
ACCESS_KEY=your-key AGENT_NAME=my-agent BACKEND_URL=agent.mindfabric.ai mindfabric-agent

# With debug mode enabled
ACCESS_KEY=your-key DEBUG_MODE=true mindfabric-agent

# With stealth mode enabled
ACCESS_KEY=your-key STEALTH_MODE=true mindfabric-agent

# All options combined
ACCESS_KEY=your-key AGENT_NAME=my-agent BACKEND_URL=agent.mindfabric.ai DEBUG_MODE=true STEALTH_MODE=true mindfabric-agent

# Note: you *can* pass ACCESS_KEY via `--access-key`, but it will be visible in process listings (`ps`, `/proc/<pid>/cmdline`).

Option 2: Run as System Service (Recommended for Production)

# Install package
pip install mindfabric-agent

# Install as systemd service (Linux only, requires sudo)
sudo mindfabric-agent-install-service

# Configure
sudo nano /etc/mindfabric-agent/agent.env

# Start service
sudo systemctl enable mindfabric-agent
sudo systemctl start mindfabric-agent

# Check status
sudo systemctl status mindfabric-agent

Option 3: Run in Docker (with Supervisor)

The Docker image automatically includes supervisor for process management. See deployment scripts for details.

Configuration

The agent uses a JSON configuration file located at config/config.json. Key configuration options:

{
  "agent_name": "your-agent-name",
  "access_key": "your-access-key", 
  "backend_url": "agent.mindfabric.ai",
  "debug_mode": false,
  "stealth_mode": false,
  "allow_remote_shell": false
}

Configuration Parameters

• agent_name: Unique name for the agent (auto-generated if not specified)
• access_key: Authentication key for connecting to the backend (required)
• backend_url: Backend server URL (default: agent.mindfabric.ai)
• debug_mode: Enable detailed logging and debug output (default: false)
• stealth_mode: Enable stealth mode for production environments (default: false)
• allow_remote_shell: Allow the backend to request ad-hoc shell execution (non-plugin commands). Default false for safety.
  • When false, the agent should only execute plugin commands (plugin:<name> ...) and reject direct shell requests.

Default Behavior

• agent_name: If not specified, a random name will be generated (e.g., "alpha-nova-1234")
• backend_url: If not specified, the agent will connect to agent.mindfabric.ai
• access_key: Required parameter - Must be specified via environment variable, config file, or command line

Command Line Arguments

All configuration parameters can be specified via command line arguments (but prefer ENV/config for secrets):

• --access-key: Authentication key (prefer ENV/config; CLI will be visible in ps)
• --agent-name: Agent name
• --backend-url: Backend server URL
• --debug: Enable debug mode
• --stealth: Enable stealth mode
• --allow-remote-shell: Allow non-plugin remote shell execution from backend/UI (unsafe; default: disabled)

Environment Variables

All configuration parameters can also be overridden using environment variables:

• AGENT_NAME: Agent name
• ACCESS_KEY: Authentication key
• BACKEND_URL: Backend server URL
• DEBUG_MODE: Enable debug mode (true/false)
• STEALTH_MODE: Enable stealth mode (true/false)
• ALLOW_REMOTE_SHELL: Allow non-plugin remote shell execution from backend (true/false). Default: false.

Priority Order

Configuration parameters are applied in the following priority order (highest to lowest):

1. Command line arguments
2. Environment variables
3. Configuration file (config/config.json)
4. Default values

Plugins

MindFabric Agent uses a plugin architecture. Plugins provide structured commands and outputs (including security findings), so you can run repeatable workflows instead of ad-hoc shell commands.

How plugins are invoked

Plugins are addressed by name, typically in the form:

• plugin:<plugin_name> <command/args>

The backend scheduler uses plugin commands for “combat runs” and automated scans.

Built-in plugins (high level)

Infra / Inventory plugins

Plugin	What it does	Why it’s useful
asset_discovery	Discovers hosts, services, ports, and relationships	Builds an inventory baseline for monitoring, triage, and attack-surface mapping
infrastructure_intelligence	Collects system metrics and detects anomalies	Adds operational visibility (unexpected spikes, processes, I/O anomalies)
database_connector	Connects to DBs for discovery and querying	Useful for inventory, verification, and controlled read-only diagnostics

Security plugins

Plugin	What it does	Why it’s useful
activedirectory_hunter	Detects Active Directory attack vectors and visibility gaps	Helps spot common AD takeover paths early (privilege abuse, lateral movement primitives)
api_security_tester	Tests API endpoints for common security hardening issues	Finds easy-to-miss API misconfigs that lead to data exposure or auth bypass
cicd_pipeline_auditor	Audits CI/CD pipeline security posture and risky defaults	CI/CD is a top compromise path; this surfaces credential/leak and signing gaps
cloud_aws_security_assesment	Cloud security assessment for AWS (IAM/exposure/logging posture)	Detects cloud misconfigurations that enable escalation and exfiltration
cloud_azure_security_assesment	Cloud security assessment for Azure (Entra/Azure resources)	Surfaces tenant/subscription misconfigurations and identity weaknesses
cloud_gcp_security_assesment	Cloud security assessment for GCP (IAM/projects visibility)	Highlights visibility gaps and dangerous cloud defaults across GCP
compliance_assessment	Compliance posture checks and control gaps	Turns “security best practice” into actionable controls and remediation tasks
database_security_assessment	Assesses database security posture and risky configs	Finds weak auth, exposure, and privilege issues in DB environments
docker_escape	Checks container escape and container hardening weaknesses	Containers are not a boundary by default; this finds breakout conditions
file_integrity_monitor	Detects suspicious changes to critical files / baselines	Useful for persistence detection and post-compromise verification
iac_security_auditor	Scans IaC (Terraform/CloudFormation/etc) for risky patterns	Stops dangerous defaults before they ship to production
ioc_scanner	Scans for Indicators of Compromise (files/paths/persistence hints)	Helps confirm compromise quickly and guide containment steps
kubernetes_escape	Kubernetes security checks and cluster escape paths	K8s misconfigs often enable cluster-wide compromise; this catches them
lateral_movement	Identifies lateral movement vectors and hardening actions	Helps reduce “pivot” paths between systems (SMB/SYSVOL/credential abuse)
lolbins_scanner	Detects LOLBins abuse opportunities and hardening recommendations	Attackers use built-in tools to blend in; hardening improves detection
memory_forensics	Memory-based suspicious behavior indicators (high-level heuristics)	Useful for catching stealthy malware techniques that avoid disk artifacts
misconfigurations_detector	Detects common misconfigurations across environments	Fast wins: finds exposed services, weak settings, and risky defaults
osint_finder	OSINT-style footprint discovery (domains, repos, leaks)	Highlights what attackers can learn without access (and where secrets leak)
persistence_detection	Detects persistence mechanisms and suspicious autoruns	Helps identify “how they stay” (cron, services, startup hooks, etc.)
privilege_escalation	Detects local privilege escalation vectors and weak permissions	Finds paths to root/admin from a foothold
process_security_scanner	Reviews running processes for risky patterns and exposure	Useful for spotting credential helpers, suspicious binaries, weak permissions
siem_analytics_evasion	Detects blind spots / evasion opportunities for monitoring	Highlights where logs/telemetry can be bypassed or are missing
ssh_pivot_hunter	Detects SSH pivoting and tunneling indicators	Catches common pivot techniques used during lateral movement
supply_chain_attack	Detects supply chain risk signals (signing/SLSA gaps)	Builds integrity into build/release pipelines to prevent tampering
user_audit	Audits users/privileges/auth artifacts (sudoers/ssh/etc)	Hardens identity surface and reduces privilege abuse opportunities
vault_security_auditor	Audits Vault posture (tokens, policies, access)	Vault misconfigs are high impact; this reduces secret-management risk
vpn_exploitation	Checks VPN-related exposure patterns and common vulnerability classes	VPNs are frequent perimeter entry points; this helps validate posture
web_application_scanner	Web app security checks (OWASP-style coverage, exposure)	Finds common web weaknesses and hardening gaps early

Security plugin outputs

Security-focused plugins emit findings in a consistent, UI-friendly structure (titles, severities, evidence previews, recommendations, and vector-specific verification commands).

Usage Examples

Basic Agent Connection

Command Line

# Simple connection
ACCESS_KEY=your-key mindfabric-agent

# With debug output
ACCESS_KEY=your-key mindfabric-agent --debug

# Custom configuration
ACCESS_KEY=your-key AGENT_NAME=my-agent BACKEND_URL=agent.mindfabric.ai mindfabric-agent

Python API

from mindfabric_agent import Agent

agent = Agent(
    agent_name="my-agent",
    access_key="my-key",
    backend_url="agent.mindfabric.ai"
)

agent.connect()
agent.run()

Using Plugins

from mindfabric_agent.plugins.database_connector import DatabaseConnectorPlugin

db_plugin = DatabaseConnectorPlugin()
result = db_plugin.execute_command("db:connect", {
    "host": "localhost",
    "port": 5432,
    "database": "mydb",
    "user": "user",
    "password": "pass"
})

Custom Plugin Development

from mindfabric_agent.plugins.base_plugin import BasePlugin

class MyCustomPlugin(BasePlugin):
    def __init__(self):
        super().__init__()
        self.name = "my-custom-plugin"
        self.version = "1.0.0"
    
    def get_commands(self):
        return ["my:command"]
    
    def execute_command(self, command, parameters):
        if command == "my:command":
            return {"status": "success", "result": "Hello from custom plugin!"}
        return {"status": "error", "message": "Unknown command"}

Development

Setting up Development Environment

1. Clone the repository:

   git clone https://github.com/mindfabric/infrastructure-agent.git
   cd infrastructure-agent/agent
   

2. Install development dependencies:

   pip install -e ".[dev]"
   

3. Run tests:

   pytest
   

Building from Source

# Install build dependencies
pip install build twine

# Build the package
python -m build

# The built packages will be in the dist/ directory

API Reference

Core Classes

• Agent: Main agent class for connecting and managing the agent
• BasePlugin: Base class for creating custom plugins
• WebSocketClient: Low-level WebSocket communication handler

Plugin Interface

All plugins must implement the BasePlugin interface:

class BasePlugin:
    def __init__(self):
        self.name = "plugin-name"
        self.version = "1.0.0"
    
    def get_commands(self):
        """Return list of supported commands"""
        return []
    
    def execute_command(self, command, parameters):
        """Execute a command with given parameters"""
        pass
    
    def get_schema(self):
        """Return command schema for validation"""
        return {}

Security Considerations

• Always use secure access keys and tokens
• Run in a secure environment with proper network isolation
• Regularly update the agent and its dependencies
• Monitor agent logs for suspicious activity
• Use stealth mode in production environments

Troubleshooting

Common Issues

1. Connection Failed: Check backend URL and network connectivity
2. Authentication Error: Verify agent name and access key
3. Plugin Loading Error: Check plugin dependencies and configuration
4. WebSocket Issues: Ensure WebSocket support and proper proxy configuration
5. Debug Mode: Use --debug flag for detailed troubleshooting information

Getting Help

# Show help and available options
mindfabric-agent --help

# Run with debug mode for detailed output
ACCESS_KEY=your-key mindfabric-agent --debug

Logging

The agent uses structured logging with multiple levels:

• DEBUG: Detailed debugging information
• INFO: General information about agent operations
• WARNING: Warning messages for potential issues
• ERROR: Error messages for failed operations

Configure debug mode in the configuration file:

{
  "debug_mode": true
}

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

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

Support

• Documentation: https://docs.mindfabric.com
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

Changelog

Version 1.1.5

• New Features:
  • Added command line argument support (--debug, --access-key, --agent-name, --backend-url, --stealth)
  • Improved configuration priority order (command line > environment variables > config file > defaults)
  • Enhanced help system with --help flag
• Improved: Better error handling and user experience
• Updated: Documentation with command line examples

Version 1.1.0

• Breaking Changes: Updated parameter names (agent_id → agent_name, backend_ws_url → backend_url)
• New Features:
  • Auto-generated agent names when not specified
  • Debug mode for detailed troubleshooting
  • Improved WebSocket URL handling (automatic ws/wss detection)
  • Enhanced connection status messages
• Removed: Legacy proxy parameters (ws_proxy_enabled, ws_proxy_url)
• Improved: Plugin loading with debug mode support

Version 1.0.0

• Initial release
• Core agent functionality
• Basic plugin system
• Database connector plugin
• Docker escape detection
• Network mapping capabilities
• OSINT gathering tools
• Secrets scanning functionality