A comprehensive security platform for managing and monitoring AI agent tool calls with fine-grained access control, policy enforcement, and audit logging.

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Agent      │    │      TCMS        │    │   External      │
│                 │───▶│   Proxy Server   │───▶│   Tools/APIs    │
│ (with API key)  │    │   (Auth+Policy)  │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────┐
                       │   Dashboard  │
                       │   Frontend   │
                       └──────────────┘

• Python 3.8+
• Node.js 18+
• npm or yarn

1. Clone the repository

   git clone https://github.com/your-username/toolshack.git
   cd toolshack

2. Install dependencies

   npm run install:all

   This installs:

   • Python backend dependencies via pip
   • Frontend React dependencies via npm

3. Set up environment variables

   # Backend environment is already configured with defaults
   # Edit backend/.env if you need custom settings

4. Initialize the database and create sample data

   npm run setup

5. Start the development servers

   npm run dev

   This starts:

   • Backend API server on http://localhost:3001
   • Frontend dashboard on http://localhost:3000

• Admin: username: admin, password: admin123
• Operator: username: operator, password: operator123

• Authentication & Authorization: JWT-based user authentication with role-based access control
• Agent API Key Management: Secure API key generation and rotation for AI agents
• Policy Engine: Dynamic policy evaluation with conditions and actions
• Human-in-the-Loop (HITL): Approval workflows for high-risk operations
• Audit Logging: Comprehensive logging of all agent activities
• Rate Limiting: Configurable rate limits to prevent abuse

The system comes with example configurations for common secure tools:

1. secure_database_query: Read-only database queries with SQL injection protection
2. access_customer_info: Customer data access with automatic PII masking
3. cloud_resource_manager: Cloud operations with approval requirements for destructive actions
4. internal_api_gateway: Internal API access with context-based policies

• Real-time Monitoring: System health, success rates, and activity metrics
• Tool Management: Register, configure, and monitor tools
• Agent Management: Create agents, manage permissions, and monitor activity
• Policy Configuration: Create and manage security policies
• Audit Trail: View and analyze all system activities

toolshack/
├── backend/                  # Python FastAPI server
│   ├── app/
│   │   ├── routers/         # API route handlers
│   │   ├── database.py      # Database models (SQLAlchemy)
│   │   └── utils/           # Authentication, logging utilities
│   ├── main.py              # FastAPI application entry point
│   ├── setup.py             # Database setup and sample data
│   └── requirements.txt     # Python dependencies
├── frontend/                 # React.js dashboard
│   ├── src/
│   │   ├── components/      # Reusable components
│   │   ├── contexts/        # React contexts
│   │   ├── pages/           # Page components
│   │   ├── services/        # API services
│   │   └── types/           # TypeScript types
│   └── package.json         # Node.js dependencies
└── docs/                    # Documentation

• FastAPI: Modern, fast web framework for building APIs
• SQLAlchemy: SQL toolkit and ORM
• SQLite: Database (easily configurable to PostgreSQL/MySQL)
• Pydantic: Data validation using Python type hints
• PyJWT: JSON Web Token implementation
• Passlib: Password hashing library
• Uvicorn: ASGI web server

• React 18: User interface library
• TypeScript: Type-safe JavaScript
• Tailwind CSS: Utility-first CSS framework
• React Query: Data fetching and caching
• React Router: Client-side routing
• React Hook Form: Form management
• Recharts: Data visualization

• POST /api/auth/login - User login
• POST /api/auth/register - Create new user (Admin only)
• GET /api/auth/me - Get current user

• POST /api/tools/execute - Execute tool call (Agent API key required)
• GET /api/tools/calls/:id - Get tool call status

• GET /api/tools - List tools
• POST /api/tools - Create tool
• PUT /api/tools/:id - Update tool
• DELETE /api/tools/:id - Delete tool

• GET /api/agents - List agents
• POST /api/agents - Create agent
• PUT /api/agents/:id - Update agent
• DELETE /api/agents/:id - Delete agent
• POST /api/agents/:id/regenerate-key - Regenerate API key

• GET /api/audit/logs - Get audit logs
• GET /api/audit/metrics - Get audit metrics
• GET /api/audit/health - System health status

# Frontend tests
npm run test

# Build frontend
npm run build

# Start production server
npm start

# Server
PORT=3001
HOST=0.0.0.0
DEBUG=True

# Database
DATABASE_URL=sqlite:///./tcms.db

# JWT Configuration
JWT_SECRET=your-super-secure-jwt-secret
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=1440

# Security
CORS_ORIGINS=["http://localhost:3000"]

# Logging
LOG_LEVEL=INFO

# Tool Configuration
TOOL_TIMEOUT_SECONDS=30
MAX_CONCURRENT_TOOL_CALLS=10

# Human-in-the-Loop
HITL_APPROVAL_TIMEOUT_MINUTES=5

{
  "name": "Business Hours Security",
  "conditions": [
    {
      "field": "hour",
      "operator": "lt",
      "value": 9,
      "logical_operator": "OR"
    },
    {
      "field": "hour",
      "operator": "gt",
      "value": 17
    }
  ],
  "actions": [
    {
      "type": "REQUIRE_APPROVAL",
      "parameters": {
        "reason": "High-risk operations require approval outside business hours"
      }
    }
  ],
  "priority": 10
}

{
  "name": "PII Masking",
  "conditions": [
    {
      "field": "tool.name",
      "operator": "equals",
      "value": "access_customer_info"
    }
  ],
  "actions": [
    {
      "type": "MASK_DATA",
      "parameters": {
        "fields": ["ssn", "credit_card", "email"]
      }
    }
  ],
  "priority": 5
}

# Build and start with Docker Compose
docker-compose up -d

1. Set up Python environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r backend/requirements.txt

2. Configure environment variables

   cp backend/.env.example backend/.env
   # Edit backend/.env with production settings

3. Initialize database

   cd backend
   python setup.py

4. Build frontend

   cd frontend
   npm run build

5. Start the production server

   cd backend
   python main.py

GET /health

• System metrics available at /api/audit/metrics
• Agent-specific activity tracking
• Real-time dashboard monitoring

• Application logs: backend/logs/tcms-YYYY-MM-DD.log
• Console output with structured logging

# Get the agent API key from setup output, then:

# Execute a tool call
curl -X POST http://localhost:3001/api/tools/execute \
  -H "X-API-Key: YOUR_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "TOOL_ID_FROM_SETUP",
    "input": {"query": "SELECT * FROM users LIMIT 5"},
    "metadata": {"source": "test"}
  }'

# Check tool call status
curl -X GET http://localhost:3001/api/tools/calls/CALL_ID \
  -H "X-API-Key: YOUR_AGENT_API_KEY"

1. Open http://localhost:3000
2. Login with admin credentials
3. Navigate to Tools to see available tools
4. Navigate to Agents to see the demo agent
5. Use the dashboard to monitor system activity

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

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

For support and questions:

1. Check the documentation
2. Search existing issues
3. Create a new issue

• WebSocket support for real-time monitoring
• Advanced policy conditions (IP-based, time-based)
• Integration with external identity providers (LDAP, SAML)
• Tool call replay and debugging features
• Advanced analytics and reporting
• Multi-tenant support
• Docker deployment configuration
• Kubernetes deployment manifests