Metadata-Version: 2.4
Name: mindfabric-agent
Version: 1.1.357
Summary: MindFabric AI Agent - Universal Infrastructure Orchestrator
Home-page: https://github.com/mindfabric/infrastructure-agent
Author: MindFabric Team
Author-email: info@mindfabric.ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: websockets>=11.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: loguru>=0.6.0
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: mysql-connector-python>=8.0.0
Requires-Dist: pymongo>=4.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: requests-unixsocket>=0.3.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: tldextract>=5.1.2
Requires-Dist: dnspython>=2.6.1
Requires-Dist: python-whois>=0.9.5
Requires-Dist: proto-plus>=1.23.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=5.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: database
Requires-Dist: psycopg2-binary>=2.9.0; extra == "database"
Requires-Dist: mysql-connector-python>=8.0.0; extra == "database"
Requires-Dist: sqlite3; extra == "database"
Provides-Extra: docker
Requires-Dist: docker>=6.0.0; extra == "docker"
Provides-Extra: kubernetes
Requires-Dist: kubernetes>=24.0.0; extra == "kubernetes"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

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

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