mindfabric-agent 1.1.8
MindFabric AI Agent - Universal Infrastructure Orchestrator
Requires Python: >=3.8

# 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)
```bash
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ mindfabric-agent
```

### From PyPI (Stable Version)
```bash
pip install mindfabric-agent
```

## Quick Start

### Option 1: Run as Command (Simple)

```bash
# 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

# Run with command line arguments (recommended)
mindfabric-agent --access-key your-key

# With custom agent name and backend URL
mindfabric-agent --access-key your-key --agent-name my-agent --backend-url agent.mindfabric.ai

# With debug mode enabled
mindfabric-agent --access-key your-key --debug

# With stealth mode enabled
mindfabric-agent --access-key your-key --stealth

# All options combined
mindfabric-agent --access-key your-key --agent-name my-agent --backend-url agent.mindfabric.ai --debug --stealth
```

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

```bash
# 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:

```json
{
  "agent_name": "your-agent-name",
  "access_key": "your-access-key", 
  "backend_url": "agent.mindfabric.ai",
  "debug_mode": false,
  "stealth_mode": 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)

### 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:

- `--access-key`: Authentication key (required)
- `--agent-name`: Agent name
- `--backend-url`: Backend server URL
- `--debug`: Enable debug mode
- `--stealth`: Enable stealth mode

### 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)

### 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 comes with several built-in plugins:

### Database Connector
- **Purpose**: Connect to and manage various database systems
- **Supports**: PostgreSQL, MySQL, SQLite, MongoDB
- **Commands**: `db:connect`, `db:query`, `db:backup`, `db:restore`

### Docker Escape
- **Purpose**: Analyze Docker containers for security vulnerabilities
- **Features**: Container escape detection, privilege escalation analysis
- **Commands**: `docker:analyze`, `docker:escape-test`, `docker:security-scan`

### Network Mapper
- **Purpose**: Discover and map network infrastructure
- **Features**: Port scanning, service detection, network topology mapping
- **Commands**: `network:scan`, `network:discover`, `network:map`

### OSINT Finder
- **Purpose**: Gather open source intelligence
- **Features**: Domain analysis, subdomain discovery, email harvesting
- **Commands**: `osint:domain`, `osint:subdomain`, `osint:email`

### Secrets Scanner
- **Purpose**: Scan for exposed secrets and sensitive information
- **Features**: API key detection, password scanning, credential analysis
- **Commands**: `secrets:scan`, `secrets:analyze`, `secrets:report`

## Usage Examples

### Basic Agent Connection

#### Command Line
```bash
# Simple connection
mindfabric-agent --access-key your-key

# With debug output
mindfabric-agent --access-key your-key --debug

# Custom configuration
mindfabric-agent --access-key your-key --agent-name my-agent --backend-url agent.mindfabric.ai
```

#### Python API
```python
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
```python
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
```python
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**:
   ```bash
   git clone https://github.com/mindfabric/infrastructure-agent.git
   cd infrastructure-agent/agent
   ```

2. **Install development dependencies**:
   ```bash
   pip install -e ".[dev]"
   ```

3. **Run tests**:
   ```bash
   pytest
   ```

### Building from Source

```bash
# 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:

```python
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

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

# Run with debug mode for detailed output
mindfabric-agent --access-key your-key --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:
```json
{
  "debug_mode": true
}
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- **Documentation**: [https://docs.mindfabric.com](https://docs.mindfabric.com)
- **Issues**: [GitHub Issues](https://github.com/mindfabric/infrastructure-agent/issues)
- **Discussions**: [GitHub Discussions](https://github.com/mindfabric/infrastructure-agent/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