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

Security plugins

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: support@mindfabric.com

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