kosh

Kosh - LAN-Based Secure File Sharing with Simulated ABE

Kosh is a modern Flask application for secure file sharing over a local network using AES encryption and simulated Attribute-Based Encryption (ABE). It features a beautiful Tailwind-based UI, an admin dashboard for user and policy management, real-time synchronization, and improved file structure for scalability.

🌟 Table of Contents

πŸš€ Quick Setup

Simple Setup for Capstone Project

1. Install Dependencies

pip install -r requirements.txt

2. Run the Application

python3 -m app.app

3. Access the Application

Open your browser: http://localhost:7130

Default Login:

4. That’s It!

The application is now running. You can:

Note: All files stored in data/ and app/uploads/. Simple JSON-based storage (no database needed). Real-time updates using WebSockets. AES encryption for all files.

πŸ“¦ Dependencies

Kosh uses minimal, well-maintained dependencies:

All dependencies are specified in requirements.txt and can be installed with:

pip install -r requirements.txt

βš™οΈ Configuration

Kosh uses a centralized configuration system (app/config.py) with environment variable support.

Environment Variables

Create a .env file from the template:

cp .env.example .env

Available configuration options:

Variable Default Description
KOSH_SECRET_KEY kosh-secret-key-change-in-production Flask secret key for sessions
KOSH_DEBUG True Enable debug mode
KOSH_HOST 0.0.0.0 Host to bind to (0.0.0.0 = all interfaces)
KOSH_PORT 7130 Port to run on
KOSH_AUDIT_RETENTION_DAYS 60 Days to keep audit logs

File Upload Configuration

Configured in app/config.py:

MAX_FILE_SIZE = 5 * 1024 * 1024 * 1024  # 5GB
ALLOWED_EXTENSIONS = {
    'txt', 'pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'csv',
    'jpg', 'jpeg', 'png', 'gif', 'zip', 'rar', 'py', 'js', 'json',
    'mp4', 'mov', 'avi', 'mkv'
}

Encryption Configuration

IV_SIZE = 16        # AES block size (bytes)
CHUNK_SIZE = 65536  # 64KB chunks for stream processing
TAG_SIZE = 32       # HMAC-SHA256 output size (bytes)

Directory Structure

Automatically created on first run:

🌐 Features

Core Features

Real-Time Features (WebSocket)

Security Features

πŸ“ Project Structure

kosh/
β”œβ”€β”€ app/
β”‚   β”œβ”€β”€ __init__.py                 # Package initialization
β”‚   β”œβ”€β”€ app.py                      # Main Flask application with routes and WebSocket handlers
β”‚   β”œβ”€β”€ attribute_management.py     # Attribute CRUD operations and role-based management
β”‚   β”œβ”€β”€ config.py                   # Centralized configuration and environment settings
β”‚   β”œβ”€β”€ utils.py                    # Shared utility functions for the application
β”‚   β”œβ”€β”€ crypto/
β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”œβ”€β”€ aes.py                  # AES-256 encryption/decryption with HMAC
β”‚   β”‚   └── abe_simulator.py        # JSON-based ABE access control simulation
β”‚   β”œβ”€β”€ static/
β”‚   β”‚   β”œβ”€β”€ admin/                  # Admin dashboard specific assets
β”‚   β”‚   β”‚   β”œβ”€β”€ admin.css
β”‚   β”‚   β”‚   β”œβ”€β”€ admin-dashboard.js
β”‚   β”‚   β”‚   └── tailwind.config.js
β”‚   β”‚   β”œβ”€β”€ dashboard/              # User dashboard specific assets
β”‚   β”‚   β”‚   β”œβ”€β”€ dashboard.css
β”‚   β”‚   β”‚   β”œβ”€β”€ dashboard.js
β”‚   β”‚   β”‚   └── dashboard-tailwind.config.js
β”‚   β”‚   β”œβ”€β”€ shared/                 # Shared components and utilities
β”‚   β”‚   β”‚   β”œβ”€β”€ components/         # Reusable UI components
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ modal.js
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ notification-manager.js
β”‚   β”‚   β”‚   β”‚   └── toast.js
β”‚   β”‚   β”‚   β”œβ”€β”€ modules/            # Feature-specific modules
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ attribute-manager.js
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ audit-manager.js
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ dashboard-file-manager.js
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ file-manager.js
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ password-manager.js
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ policy-manager.js
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ realtime-manager.js
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ role-manager.js
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ role-manager-attribute.js
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ upload-manager.js
β”‚   β”‚   β”‚   β”‚   └── user-manager.js
β”‚   β”‚   β”‚   └── utils/              # UI helper utilities
β”‚   β”‚   β”‚       β”œβ”€β”€ admin-links.js
β”‚   β”‚   β”‚       └── ui-helpers.js
β”‚   β”‚   └── common/                 # Common assets (favicons, icons, PWA manifest)
β”‚   β”‚       β”œβ”€β”€ android-chrome-192x192.png
β”‚   β”‚       β”œβ”€β”€ android-chrome-512x512.png
β”‚   β”‚       β”œβ”€β”€ apple-touch-icon.png
β”‚   β”‚       β”œβ”€β”€ favicon-16x16.png
β”‚   β”‚       β”œβ”€β”€ favicon-32x32.png
β”‚   β”‚       β”œβ”€β”€ favicon.ico
β”‚   β”‚       └── site.webmanifest
β”‚   β”œβ”€β”€ templates/
β”‚   β”‚   β”œβ”€β”€ index.html              # Login page
β”‚   β”‚   β”œβ”€β”€ dashboard.html          # User dashboard
β”‚   β”‚   └── admin.html              # Admin dashboard
β”‚   └── uploads/                    # Encrypted file storage (auto-created)
β”œβ”€β”€ data/
β”‚   β”œβ”€β”€ aes_encryption.key          # AES encryption key (auto-generated)
β”‚   β”œβ”€β”€ aes_hmac.key                # HMAC key for integrity (auto-generated)
β”‚   β”œβ”€β”€ attributes.json             # Global attribute pool
β”‚   β”œβ”€β”€ audit_logs.jsonl            # System audit logs (JSONL format)
β”‚   β”œβ”€β”€ policies.json               # File access policies
β”‚   └── users.json                  # User accounts and attributes
β”œβ”€β”€ .github/                        # GitHub templates and workflows
β”‚   └── ISSUE_TEMPLATE/
β”‚       β”œβ”€β”€ bug_report.md
β”‚       └── feature_request.md
β”œβ”€β”€ .env.example                    # Environment configuration template
β”œβ”€β”€ .gitignore                      # Git ignore patterns
β”œβ”€β”€ requirements.txt                # Python dependencies
β”œβ”€β”€ LICENSE                         # License information
└── README.md                       # This file

πŸš€ Getting Started

Prerequisites

1. Clone the Repository

git clone https://github.com/neelshha/kosh.git
cd kosh

2. Set Up Virtual Environment

python -m venv venv
source venv/bin/activate        # On macOS/Linux
# or
venv\Scripts\activate           # On Windows
pip install -r requirements.txt

3. Configure Environment (Optional)

The application works with default settings, but you can customize it:

cp .env.example .env
# Edit .env file to customize settings

Available environment variables:

4. Run the Application

python -m app.app

The application will:

You can access it from any device on the same local network.

5. Default Login Credentials

6. Admin Dashboard Access

πŸ”„ Real-Time Features

Kosh includes comprehensive real-time synchronization using WebSocket technology (Socket.IO):

Live Updates

WebSocket Events

Testing Real-Time Features

Open multiple browser tabs as admin to see live synchronization:

  1. Login as admin in multiple tabs
  2. Perform operations in one tab
  3. Observe instant updates in all other tabs

Technical Implementation

Backend (Flask-SocketIO)

# Admin room management
@socketio.on('join_admin')
def handle_join_admin():
    user_id = session.get('user_id')
    if user_id == 'admin':
        join_room('admin_updates')
        emit('joined_admin', {'message': 'Joined admin updates'})

# Real-time event emission
socketio.emit('user_added', {
    'user': user_id,
    'attributes': attributes,
    'timestamp': datetime.now().strftime('%Y-%m-%d %H:%M:%S')
}, room='admin_updates')

Frontend (JavaScript + Socket.IO)

// Initialize connection
const socket = io();
socket.emit('join_admin');

// Listen for real-time events
socket.on('user_added', function(data) {
    addUserToTable(data.user, data.attributes);
    showToast(`User "${data.user}" added`, 'success');
});

Configuration

For production environments, configure specific CORS origins:

socketio = SocketIO(app, cors_allowed_origins=["https://yourdomain.com"])

Browser Compatibility

Real-time features work in all modern browsers supporting WebSocket:

πŸ”’ Security

Encryption Implementation

AES-256-CTR with HMAC-SHA256

All files are encrypted using industry-standard AES-256 in CTR mode with HMAC authentication:

Encryption Format:

[16-byte IV][Encrypted File Data][32-byte HMAC Tag]

Key Files:

Access Control

Attribute-Based Access Control (ABE Simulation)

Role-Based Permissions

Authentication & Session Management

Input Validation & Security

Audit Trail

Default Password Implementation

All users have a consistent password structure:

The system automatically converts legacy user formats to the new dictionary format:

{
  "username": {
    "attributes": ["attr1", "attr2"],
    "password": "hashed_password"
  }
}

Security Best Practices

For Production Deployment:

  1. Change Secret Key: Set KOSH_SECRET_KEY environment variable
  2. Change Default Passwords: Update all user passwords
  3. Disable Debug Mode: Set KOSH_DEBUG=False
  4. Use HTTPS: Deploy behind reverse proxy with SSL/TLS
  5. Restrict CORS: Configure specific origins in production
  6. Network Isolation: Use on trusted local network only
  7. File Permissions: Ensure proper permissions on data/ directory
  8. Regular Backups: Backup data/ directory regularly
  9. Monitor Audit Logs: Review logs for suspicious activity
  10. Update Dependencies: Keep Python packages up to date

Known Limitations

Reporting Security Vulnerabilities

Please report security vulnerabilities by creating an issue with the β€œsecurity” label.

Supported Versions:

Version Supported
5.1.x βœ…
5.0.x ❌
4.0.x βœ…
< 4.0 ❌

Include in your report:

πŸ—οΈ Architecture

Modular Design

Kosh follows a modular architecture with clear separation of concerns:

Backend Components

Core Application (app.py)

Configuration Module (config.py)

Centralizes all application settings:

Utility Module (utils.py)

Shared helper functions:

Attribute Management Module (attribute_management.py)

Dedicated blueprint for attribute operations:

Crypto Module

Frontend Architecture

Modular JavaScript Structure

The frontend follows a component-based architecture with three layers:

1. Components (static/shared/components/)

Reusable UI components:

2. Modules (static/shared/modules/)

Feature-specific functionality:

3. Utilities (static/shared/utils/)

Helper functions:

Dashboard-Specific Assets

Data Layer

JSON-Based Storage

Simple, file-based data persistence:

users.json - User accounts with attributes and passwords

{
  "username": {
    "attributes": ["attr1", "attr2"],
    "password": "hashed_password"
  }
}

attributes.json - Global attribute pool

["finance", "engineering", "hr", "executive"]

policies.json - File access policies

{
  "encrypted_filename.enc": {
    "policy": ["finance", "executive"],
    "key": "encrypted_file_key",
    "uploader": "admin",
    "timestamp": "2025-11-07 10:30:45"
  }
}

audit_logs.jsonl - Activity logs (JSON Lines format)

{"user": "admin", "action": "add_user", "details": "Added user: john", "time": "2025-11-07 10:30:45", "ip": "127.0.0.1"}

Request Flow

File Upload Flow:

  1. User selects file and defines access policy
  2. Frontend validates file and sends to /upload endpoint
  3. Backend encrypts file with AES-256-CTR
  4. Generates encrypted file key with policy
  5. Stores encrypted file in app/uploads/
  6. Saves policy metadata to policies.json
  7. Logs action to audit log
  8. Emits WebSocket event to update all connected clients

File Download Flow:

  1. User requests file via /download/<filename>
  2. Backend loads policy from policies.json
  3. ABE simulator checks if user has required attributes
  4. If authorized, decrypts file in memory
  5. Streams decrypted file to user
  6. Logs download action to audit log

Real-Time Update Flow:

  1. Admin performs action (add user, update policy, etc.)
  2. Backend processes request and updates data files
  3. Logs action to audit_logs.jsonl
  4. Emits WebSocket event with update data
  5. All connected admin clients receive event
  6. Frontend modules update UI reactively
  7. Toast notification confirms action

Key Features Implementation

Attribute-Based Access Control:

Role-Based Administration:

Audit Trail:

Dashboard Architecture

The application features a well-structured dashboard system with separated concerns:

Admin Dashboard

Located at /admin, provides comprehensive administrative functionality:

Features:

Structure:

app/static/admin/
β”œβ”€β”€ admin.css                    # Admin-specific styles
β”œβ”€β”€ admin-dashboard.js           # Main admin controller
└── tailwind.config.js           # Tailwind configuration

User Dashboard

Located at /dashboard, provides user-facing functionality:

Features:

Structure:

app/static/dashboard/
β”œβ”€β”€ dashboard.css                # User dashboard styles
β”œβ”€β”€ dashboard.js                 # Main dashboard controller
└── dashboard-tailwind.config.js # Tailwind configuration

Shared Components

Reusable components and modules used across both dashboards:

app/static/shared/
β”œβ”€β”€ components/              # UI components
β”‚   β”œβ”€β”€ modal.js            # Generic modal system
β”‚   β”œβ”€β”€ toast.js            # Toast notifications
β”‚   └── notification-manager.js
β”œβ”€β”€ modules/                 # Feature modules
β”‚   β”œβ”€β”€ realtime-manager.js # WebSocket handling
β”‚   β”œβ”€β”€ user-manager.js     # User CRUD
β”‚   β”œβ”€β”€ attribute-manager.js
β”‚   β”œβ”€β”€ policy-manager.js
β”‚   β”œβ”€β”€ file-manager.js
β”‚   β”œβ”€β”€ upload-manager.js
β”‚   β”œβ”€β”€ password-manager.js
β”‚   β”œβ”€β”€ audit-manager.js
β”‚   β”œβ”€β”€ role-manager.js
β”‚   β”œβ”€β”€ role-manager-attribute.js
β”‚   └── dashboard-file-manager.js
└── utils/                   # Helper utilities
    β”œβ”€β”€ ui-helpers.js
    └── admin-links.js

Key Benefits

πŸ’» Development

API Endpoints

Authentication Routes

User Dashboard Routes

Admin Routes

Policy Management Routes

Attribute Management Routes (Blueprint)

Audit Routes

WebSocket Events

Connection Events:

Server-Emitted Events:

Code Style Guidelines

Adding New Features

Backend Real-Time Events

# Emit events after data changes
from flask import current_app
socketio = current_app.extensions.get('socketio')
utils.emit_socketio_event(socketio, 'custom_event', data, room='admin_updates')

Frontend Event Handling

// Listen for events and update UI
socket.on('custom_event', function(data) {
    updateUIElement(data);
    showToast('Action completed', 'success');
});

Event Naming Convention

UI Update Best Practices

Performance Considerations

Testing Guidelines

Testing Real-Time Features:

Open multiple browser tabs as admin to see live synchronization:

  1. Login as admin in multiple tabs
  2. Perform operations in one tab
  3. Observe instant updates in all other tabs

Testing File Access Control:

  1. Create users with different attributes
  2. Upload files with varying policy requirements
  3. Login as different users to verify access control
  4. Check audit logs for all operations

🀝 Contributing

We welcome contributions from the community! Whether it’s fixing a bug, improving documentation, or adding a new feature, all contributions are welcome.

Getting Started

  1. Fork the Repository: Click the Fork button in the top-right corner
  2. Clone your fork locally: 
    git clone https://github.com/<your-username>/kosh.git
cd kosh
  3. Set upstream remote (recommended): 
    git remote add upstream https://github.com/neelshha/kosh.git
  4. Create a feature branch: 
    git checkout -b feature/<short-description>

Contribution Guidelines

Commit Message Format

Follow Conventional Commits:

<type>: <short description>

feat: add real-time file upload progress
fix: resolve WebSocket connection issues
docs: update installation instructions
refactor: restructure dashboard components
style: formatting changes, no code logic updates
test: adding or updating tests

Code Requirements

Types of Contributions

Issue Templates

Use our GitHub issue templates for:

Bug Reports

Feature Requests

Pull Request Process

  1. Ensure code quality: Make sure your code is tested and follows our guidelines
  2. Update documentation: Include relevant documentation updates
  3. Test thoroughly: Verify your changes work across different scenarios
  4. Push your branch: 
    git push origin feature/<branch-name>
  5. Open a Pull Request: Provide a clear title and description, link related issues

Development Setup

  1. Set up virtual environment as described in Getting Started
  2. Install development dependencies if any
  3. Run the application locally to test changes
  4. Use multiple browser tabs to test real-time features

πŸ“‹ License

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

Copyright (c) 2025 Kavish Shah

Disclaimer

Kosh is designed for educational purposes and internal LAN use. It should not be exposed to the public internet without proper security hardening, including:

The authors are not responsible for any data loss, security breaches, or other issues arising from the use of this software.

πŸ™ Acknowledgments

Special thanks to all contributors who have helped make Kosh better:

Technologies & Libraries

Inspiration

Kosh was created as a capstone project to demonstrate:

πŸ“ž Support

For questions, bug reports, or feature requests:

πŸ’‘ Common Use Cases

Example 1: Department-Based File Sharing

Scenario: Share financial reports only with finance and executive teams

  1. Create attributes: finance, executive
  2. Create users:
    • John (finance department): attributes = finance
    • Sarah (CEO): attributes = executive, finance
  3. Upload report with policy: finance, executive
  4. Result: Both John and Sarah can access the file

Example 2: Project-Based Access Control

Scenario: Share project files with team members

  1. Create attributes: project_alpha, engineering, design
  2. Upload design files with policy: project_alpha, design
  3. Upload code files with policy: project_alpha, engineering
  4. Only users with both project_alpha AND the respective attribute can access

Example 3: Role Manager Delegation

Scenario: HR manager needs to assign attributes to employees

  1. Admin assigns role_manager role to HR user
  2. HR user can now assign attributes to other users
  3. HR user cannot add/remove global attributes (admin only)
  4. All changes logged in audit trail

πŸ”§ Troubleshooting

Application Won’t Start

Problem: ModuleNotFoundError or import errors

Solution:

# Ensure you're in the virtual environment
source venv/bin/activate  # On macOS/Linux
venv\Scripts\activate     # On Windows

# Reinstall dependencies
pip install -r requirements.txt

Can’t Access from Other Devices

Problem: Application only accessible from localhost

Solution:

File Upload Fails

Problem: Large file uploads fail or timeout

Solution:

WebSocket Disconnections

Problem: Real-time updates stop working

Solution:

Audit Logs Growing Too Large

Problem: audit_logs.jsonl consuming too much disk space

Solution:

Password Reset

Problem: Forgot admin password

Solution:

  1. Edit data/users.json
  2. Change admin password to default: 
    {
  "admin": {
    "attributes": [],
    "password": "pass"
  }
}
  3. Restart application
  4. Login with admin / pass
  5. Change password immediately

Permission Denied Errors

Problem: Can’t create files in data/ or app/uploads/

Solution:

# Fix directory permissions
chmod 755 data/
chmod 755 app/uploads/

Real-Time Features Not Working

Problem: Admin dashboard doesn’t update in real-time

Solution:

πŸš€ Future Roadmap

Planned enhancements for future versions:

Real-Time Features

Security Enhancements

User Experience

Administration

Technical Improvements

Mobile & Accessibility

File Management

Integration & Extensibility

Developer Tools

Contributions welcome! If you’d like to work on any of these features, please create an issue or submit a pull request.

Happy file sharing with Kosh! πŸ”πŸ“

This site is open source. Improve this page.