System Requirements Document (SRD)

amber-scanner

1. Introduction

The amber-scanner project is a web-based system designed to scan all public GitHub repositories for exposed AI API keys (e.g., OpenAI, Anthropic, Google AI, etc.) every two minutes. The system detects, validates, and displays findings on a live dashboard, including the GitHub repository URL, the exact file path, and the location where the exposed key is detected.

This system is intended strictly for educational purposes, aiming to raise awareness about the risks of exposed API keys and to demonstrate practical methods for detecting and mitigating such risks. It is not intended for malicious use or unauthorized access to sensitive data.

This document outlines the system's requirements, features, and design considerations to ensure clarity and alignment with the project's goals.

2. System Overview

The amber-scanner system operates as an educational tool to demonstrate the importance of securing API keys in public repositories. It autonomously scans public GitHub repositories at regular intervals (every two minutes) and provides a live dashboard for users to view the results.

Key features include:

• Automated scanning of public GitHub repositories.
• Validation of detected API keys to confirm their authenticity.
• Display of findings, including repository URL, file path, and key location, on a live dashboard.
• Option for users to input their GitHub API key to connect and customize scanning.

The system is designed for educational purposes and is not intended for commercial use or to infringe on the privacy of GitHub users.

3. Functional Requirements

As User:

• I should be able to view a live dashboard displaying exposed API keys detected in public GitHub repositories.
• I should be able to see details such as the repository URL, file path, and location of the exposed key.
• I should be able to input my GitHub API key to connect and customize scanning.

As System:

• The system should scan all public GitHub repositories every two minutes for exposed AI API keys.
• The system should validate detected API keys to confirm their authenticity.
• The system should display findings in real-time on the dashboard.

4. User Personas

1. Student/Developer

   • Description: Individuals learning about secure coding practices and API key management.
   • Goals: Understand the risks of exposed API keys and learn how to detect and mitigate such risks.
   • Interactions: View the live dashboard, input GitHub API keys for customized scanning.

2. Educator/Trainer

   • Description: Professionals teaching secure coding practices and cybersecurity awareness.
   • Goals: Use the system as a teaching tool to demonstrate real-world consequences of exposed API keys.
   • Interactions: Monitor the dashboard, guide students through the scanning process.

5. Visuals Colors and Theme

Unique Color Palette for amber-scanner:

• Background: #0A1F44 (Deep Navy Blue)
• Surface: #142850 (Dark Blue)
• Text: #E8F1F2 (Soft White)
• Accent: #F9A826 (Vibrant Amber)
• Muted Tones: #27496D (Muted Blue-Grey)

This palette reflects a professional yet engaging aesthetic, with amber accents symbolizing the project's name and purpose.

6. Signature Design Concept

Interactive "Code Matrix" Dashboard

The homepage/landing page will feature an animated "code matrix" background that mimics the look of scrolling code snippets. These snippets will dynamically update to show real-time scanning activity, such as repository names and detected API keys (obfuscated for privacy).

Key features of the design:

• Interactive Repository Map: A central, interactive map of the GitHub ecosystem, where users can hover over nodes (representing repositories) to see scanning activity and results.
• Key Detection Animation: When an exposed key is detected, a glowing amber highlight will pulse on the map, drawing attention to the affected repository.
• Dynamic Stats Panel: A sidebar will display real-time statistics, such as the number of repositories scanned, keys detected, and common file types where keys are exposed.
• Micro-interactions: Hover effects on buttons and links will create a ripple effect in the amber accent color.

This design will create an immersive and visually striking experience, making the educational purpose of the system both engaging and memorable.

7. Non-Functional Requirements

• Performance: The system should scan all public GitHub repositories within a two-minute interval without significant delays.
• Scalability: The system should handle increased scanning loads as the number of public repositories grows.
• Security: User-provided GitHub API keys should be securely stored and encrypted.
• Reliability: The system should maintain 99.9% uptime to ensure consistent scanning and dashboard availability.
• Localization: The system should support the Indian timezone (IST) for scheduling and timestamps.

8. Tech Stack

Frontend:

• React for Web

Backend:

• Python
• FastAPI

Database:

• MySQL (with Alembic for migrations)

AI Models:

• GPT 5.4 for user-friendly responses

AI Tools:

• Langchain
• Litellm for LLM Routing

Orchestration:

• Docker
• Kubernetes

9. Assumptions and Constraints

• The system will only scan public GitHub repositories and will not access private repositories.
• The system is intended for educational purposes only and should not be used for malicious activities.
• Users must provide their own GitHub API key for customized scanning.
• The system will operate in the Indian timezone (IST) by default.

10. Glossary

• API Key: A unique identifier used to authenticate requests associated with a specific application or user.
• GitHub Repository: A storage space on GitHub where project files are stored and managed.
• Dashboard: A user interface that provides real-time data and insights.
• IST: Indian Standard Time, the time zone used in India (UTC+5:30).
• Educational Purpose: The use of the system solely for learning and awareness, without any commercial or malicious intent.