CyberClash Application

A secure FastAPI application demonstrating Authentication, Role-Based Access Control (RBAC), SSH Access Management, and Comprehensive Logging.

Features

• Secure Authentication: Username, Password, and TOTP (Two-Factor Authentication).
• RBAC: Distinction between admin and user roles.
• SSH Registry: Manage access to SSH servers based on hierarchy.
• Logging: Detailed audit logs for all events, including frontend errors and authentication attempts.
• Security First: "Don't Trust, Verify" architecture ensuring database validation for every request.

Setup

Prerequisites

• Python 3.10+
• pip

Installation

1. Clone/Download the repository.
2. Configuration: Create a .env file in the root directory:

   SECRET_KEY="your-secure-secret-key"
   DATABASE_URL="sqlite:///./users.db"
   LOGS_PASSWORD="admin-secret-logs-password"

3. Startup: Run the helper script to install dependencies and start the server:

   ./start.sh

Usage

User Registration

Use the CLI script to create new users:

python3 register.py

• Follow the prompts.
• Scan the provided key or provisioning URI with Google Authenticator.

Authentication (POST /login)

Authenticate to receive a JWT Bearer Token. Body:

{
  "username": "...",
  "password": "...",
  "totp_code": "..."
}

Response: access_token

SSH Registry

• List Servers (GET /ssh/list): Returns a list of servers accessible to your role.
  • admin: Sees ALL servers.
  • user: Sees only public servers.
• Connect (GET /ssh/{id}): Returns connection details if authorized.
  • Response: {"host": "...", "username": "...", "command": "ssh ..."}
• Add Server (PUT /ssh/put) (Admin Only): Adds a new server to the registry.
  • Body: {"name": "...", "host": "...", "username": "...", "required_role": "..."}

File Management

• Upload File (POST /file/post): Upload a text file securely.
  • Body: {"filename": "...", "content": "...", "required_role": "..."}
• List Files (GET /file/list): List files available to your role.
• Retrieve File (GET /file/get/{id}): Get content of a file if authorized.

User Management (Admin Only)

• List Users (GET /users/): See all registered users and their roles.
• Create User (POST /users/create_with_secret): Create a new user. Returns the totp_secret for provisioning.
  • Body: {"username": "...", "password": "...", "role": "..."}

Chat System

• List Chats (GET /chat/list): See all conversations you are part of.
• Start Chat/Send Message (POST /chat/new): Send a message to a user. Creates a new chat if one doesn't exist.
  • Body: {"recipient": "...", "content": "..."}
• Inbox (GET /chat/inbox/all): View all incoming messages.
• Outbox (GET /chat/outbox/all): View all sent messages.
• View Chat (GET /chat/{id}): View message history for a specific chat. Forbidden if you are not a participant.

Logs

• View Logs (GET /logs): Protected endpoint to export categorized logs.
  • Header: x-logs-password (Must match .env)
  • Categories: AUTH, ACCESS, SYSTEM, SSH, FILE, CHAT, FRONTEND.
• Submit Log (POST /log): Ingest logs from frontend clients.
  • Body: {"sub_category": "...", "contents": "..."}

Security Internals

• Password Hashing: Bcrypt.
• Tokens: JWT (HS256). Token claims include role.
• Verification: All authenticated endpoints verify the user's status against the live database (get_current_user).

Audit Logging

All events are logged to app.log.

Note: To support security audits (and honeypot analysis), login attempts explicitly log provided passwords.

Development

To re-seed the database with default users (testuser / admin, guest / user):

rm users.db
python3 seed_db.py