____                                     _  ____                     _      ____                       _ _         
 |  _ \ __ _ ___ _____      _____  _ __ __| |/ ___|_   _  __ _ _ __ __| |    / ___|  ___  ___ _   _ _ __(_) |_ _   _ 
 | |_) / _` / __/ __\ \ /\ / / _ \| '__/ _` | |  _| | | |/ _` | '__/ _` |____\___ \ / _ \/ __| | | | '__| | __| | | |
 |  __/ (_| \__ \__ \\ V  V / (_) | | | (_| | |_| | |_| | (_| | | | (_| |_____|__) |  __/ (__| |_| | |  | | |_| |_| |
 |_|   \__,_|___/___/ \_/\_/ \___/|_|  \__,_|\____|\__,_|\__,_|_|  \__,_|    |____/ \___|\___|\__,_|_|  |_|\__|\__, |
                                                                                                               |___/ 

This project was not created to solve a client requirement or academic assignment. It emerged from personal curiosity and a deep passion for understanding the intricate mechanisms of digital security. It serves as a testament to the belief that robust security tools should be accessible, transparent, and built with user privacy as the foremost consideration.

In an era where data breaches are ubiquitous, relying on simple regex checks (e.g., "must contain one uppercase letter") is insufficient for securing digital identities. We observed a gap between complex, command-line security auditing tools and overly simplistic web-based password meters. We built CyberGuard to bridge this gap, offering advanced entropy analysis and real-time breach detection directly within the browser, without ever compromising user privacy.

This project was developed as a comprehensive submission for the Adaovi cybersecurity internship hackathon. It represents a synthesis of modern web development practices and fundamental cryptographic principles, assembled by individuals dedicated to advancing usable security.

1. Privacy-Preserving Verification: The primary challenge was validating passwords against known breaches without exposing the plaintext password to external servers.
2. Client-Side Hashing Performance: Implementing efficient SHA-1 hashing purely in the browser using the Web Crypto API, ensuring non-blocking operations during real-time typing.
3. Accurate Strength Metrics: Moving beyond binary pass/fail regex models to a granular, weighted scoring system that accurately reflects algorithmic entropy and pattern predictability.

CyberGuard is engineered entirely with Vanilla JavaScript, HTML5, and CSS3. We intentionally avoided heavy frameworks (like React or Vue) to ensure a zero-dependency architecture. This drastically reduces the supply chain attack surface and results in an extremely lightweight, performant application. The core engine utilizes asynchronous JavaScript (Promises/Async-Await) to interface with the Web Crypto API for secure random number generation and hashing.

Security tools often suffer from poor user experience, leading to low adoption rates. We prioritized a sleek, dark-mode, high-tech interface (Inter typography, glassmorphic elements, smooth state transitions) to make security engaging. The UI provides immediate, actionable feedback rather than generic warnings, guiding the user toward better security practices without friction.

• K-Anonymity in Practice: Implementing the Have I Been Pwned API solidified our understanding of K-Anonymity, demonstrating how partial hashes can be securely exchanged to verify full hash existence.
• Cryptographic Randomness: We learned the critical distinction between pseudo-random (Math.random()) and cryptographically secure random (window.crypto.getRandomValues()), essential for the password generator.

• WebAssembly (Wasm) implementation of hashing algorithms for even faster, native-speed processing.
• A browser extension variant of CyberGuard for seamless credential auditing across platforms.
• Native mobile application wrappers using progressive web app (PWA) standards.

1. Introduction
2. Technology Stack
3. Core Features
4. System Architecture
   • High-Level Architecture
   • Workflow Diagram
   • Sequence Diagram
5. Directory Structure
6. Installation & Deployment
7. API & Internal Methods Documentation
8. Security & Privacy Model
9. Scalability Considerations
10. Configuration & Customization
11. Testing Documentation
12. Troubleshooting Guide
13. Contributing
14. License
15. Frequently Asked Questions (FAQ)

CyberGuard is a state-of-the-art, client-side web application designed to evaluate, verify, and generate secure passwords. Unlike traditional password checkers that send plaintext passwords to a server for analysis—introducing massive security vulnerabilities—CyberGuard performs all entropy calculations and cryptographic hashing locally within the user's browser.

The system leverages the highly respected Have I Been Pwned (HIBP) API via a strict K-Anonymity protocol to cross-reference user input against billions of known breached passwords. This ensures that users are immediately alerted if their chosen credential has been compromised in past data leaks, allowing them to take proactive defensive measures.

CyberGuard is built upon a robust, zero-dependency foundation to ensure maximum security, performance, and maintainability.

• Frontend Interface: HTML5 (Semantic Structure)
• Styling: CSS3 (Vanilla CSS, CSS Variables, Flexbox, CSS Grid)
• Core Logic & Computation: Modern JavaScript (ES6+, Async/Await)
• Cryptography: Web Crypto API (window.crypto.subtle, window.crypto.getRandomValues)
• External Integration: HIBP API v3 (RESTful over HTTPS)
• Hosting / Infrastructure: Any standard static file hosting (GitHub Pages, Cloudflare Pages, Vercel, AWS S3, Nginx)

As the user types, the input is continuously analyzed against multiple vectors: length, character diversity, and pattern predictability. The engine strictly computes true mathematical entropy ($E = L \times \log_2(R)$) and displays it live. A rigorous offline "Time-to-Crack" estimator determines resistance against modern brute-force hardware, mapping directly to the 2025 Hive Systems password metrics (scaling up to "463qn+ years").

CyberGuard hashes the password using SHA-1 locally. Only the first 5 characters of the resulting hex string are transmitted to the HIBP API. The API returns a list of all breached suffixes matching that prefix. The local client then searches this list for the remaining characters of the user's hash.

A built-in utility allows users to specify constraints and an optional "Memorable Keyword". To guarantee enterprise-grade unpredictability:

• 12-Character Minimum: Strict enforcement of a minimum length of 12 characters to ensure baseline cryptographic safety.
• Zero-Preservation: The user's keyword is hashed using SHA-256, and the hash bytes are used to mathematically XOR the raw CSPRNG output. The original keyword characters NEVER survive in the plaintext password.
• CSPRNG Dominance: 100% of the character generation relies on hardware-backed randomness (window.crypto.getRandomValues).
• Category Guarantee: Mathematically guarantees the inclusion of at least one character from every selected category.
• Fisher-Yates Shuffle: A cryptographically secure array shuffle ensures zero predictable structural layout.

• Session History: Temporarily logs the last 5 generated passwords locally, ensuring users never accidentally lose a generated credential.
• Secure Clipboard: 1-click clipboard integration for quickly and securely copying passwords.
• Zero-Dependency Engine: Built entirely locally to bypass tracking prevention algorithms and operate 100% offline (excluding the HIBP API).

The architecture of CyberGuard is designed to be fully decentralized from any proprietary backend. The browser acts as the primary compute node, interfacing directly with external public APIs only when absolutely necessary, and only with anonymized data.

graph TD
    subgraph Client [Client Browser Environment]
        UI[User Interface HTML/CSS]
        Logic[Core Logic Engine script.js]
        Crypto[Web Crypto API]
        Analyzer[Entropy Analyzer]
        Generator[Password Generator]
    end

    subgraph External [External Services]
        HIBP[Have I Been Pwned API]
    end

    UI <-->|Input/Feedback| Logic
    Logic -->|Request Randomness| Crypto
    Logic -->|Hash Password| Crypto
    Logic <-->|Calculate Score| Analyzer
    UI -->|Request Generation| Generator
    Generator -->|Secure Seed| Crypto
    Generator -->|Output String| UI
    Logic -->|GET /range/{prefix}| HIBP
    HIBP -->|Return Suffix List| Logic

This workflow illustrates the exact process that occurs when a user inputs a password into the analysis field. Notice the debounce mechanism which prevents API rate-limiting during rapid typing.

flowchart TD
    A[User Types Password] --> B{Length > 0?}
    B -- No --> C[Reset UI State]
    B -- Yes --> D[Run Entropy Analysis]
    D --> E[Update UI Strength Meter & Tips]
    E --> F{Length >= 6?}
    F -- No --> G[Wait for more input]
    F -- Yes --> H[Trigger 500ms Debounce]
    H --> I[Execute Web Crypto SHA-1 Hash]
    I --> J[Extract Prefix first 5 chars]
    I --> K[Extract Suffix remaining chars]
    J --> L[Fetch HIBP API: /range/Prefix]
    L --> M{Match Found in Response?}
    M -- Yes --> N[Display Breach Warning UI]
    M -- No --> O[Maintain Secure UI State]

The following sequence diagram details the precise network interactions during the breach detection phase, emphasizing the K-Anonymity implementation.

sequenceDiagram
    participant User
    participant Browser
    participant WebCrypto
    participant HIBP_API

    User->>Browser: Types "password123"
    Browser->>WebCrypto: digest("SHA-1", "password123")
    WebCrypto-->>Browser: returns hash: "CBFDAAC86E07E9865108DBE06A9F88CB21F33F17"
    Browser->>Browser: Split Hash: Prefix "CBFDA", Suffix "AC86E07E9865108DBE06A9F88CB21F33F17"
    Browser->>HIBP_API: GET https://api.pwnedpasswords.com/range/CBFDA
    HIBP_API-->>Browser: Returns text list of suffixes and counts
    Browser->>Browser: Scan list for Suffix "AC86E...F17"
    alt Match Found
        Browser->>User: Renders Warning: Password Compromised
    else No Match
        Browser->>User: Renders Safe State
    end

The project relies on a clean, modular file structure, separating presentation, styling, and behavioral logic.

PasswordGuard-Security/
│
├── index.html          # Main application entry point and DOM structure
├── style.css           # Styling rules, CSS variables, dark-mode theme
├── script.js           # Core logic, crypto implementation, API handling
├── logo.png            # Application logo and favicon
└── README.md           # Extensive technical documentation

• index.html: Contains the semantic markup. It utilizes SVG icons for high-resolution rendering and implements accessibility features like aria-label for screen readers.
• style.css: Defines the visual identity. Key aspects include CSS custom properties (:root) for easy theming, flexbox/grid for responsive layout, and hardware-accelerated transitions for smooth UI updates.
• script.js: The engine room. Contains event listeners, debouncing logic, the analyzePassword algorithm, the generateSecurePassword function, and the checkPwnedPassword asynchronous routine.

Due to its static nature, CyberGuard requires no backend compilation, database provisioning, or complex environment setup. It is ready for deployment out of the box.

1. Clone the repository:

   git clone https://github.com/TheOrionGD/PasswordGuard-Security.git
   cd PasswordGuard-Security

2. Serve the files: While you can simply double-click index.html to open it via the file:// protocol, using a local development server is recommended to avoid CORS issues with the Web Crypto API on some strict browsers.

   Using Python:

   python -m http.server 8000

   Using Node.js (http-server):

   npx http-server -p 8000

3. Access the application: Navigate to http://localhost:8000 in your web browser.

Deploying to production involves serving the static files over a secure HTTPS connection. HTTPS is strictly required, as modern browsers restrict access to window.crypto.subtle in insecure contexts.

1. Push your code to the main branch.
2. Navigate to your repository settings on GitHub.
3. Select "Pages" from the left sidebar.
4. Under "Build and deployment", set the Source to "Deploy from a branch".
5. Select main as the branch and / (root) as the folder.
6. Click Save. Your application will be live within minutes.

Create the following Dockerfile in the root directory:

FROM nginx:alpine
COPY . /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Build and run:

docker build -t cyberguard .
docker run -d -p 8080:80 cyberguard

While CyberGuard is a frontend application, its internal Javascript architecture is built around highly modular, documented functions.

Evaluates the raw password string and calculates a security score based on deterministic rules.

• Parameters:
  • password (String): The plaintext input provided by the user.
• Returns:
  • Object:
    • score (Number): An integer between 0 and 100.
    • strength (String): A categorical rating ("Weak", "Medium", "Strong").
    • feedback (Array): A list of actionable strings (e.g., ["Add numbers."]).

Implementation Detail: The function uses regular expressions to test for character classes (/[A-Z]/, /[a-z]/, /[0-9]/, /[\W_]/). Deductions are heavily applied if the password consists entirely of a single character type (e.g., all lowercase letters).

Generates a random string based on boolean constraints using cryptographic entropy.

• Parameters:
  • length (Number): Desired output length.
  • upper, lower, numbers, symbols (Boolean): Character set inclusion flags.
• Returns:
  • String: The generated secure password.

Code Snippet:

const randomValues = new Uint32Array(length);
window.crypto.getRandomValues(randomValues);

let password = '';
for (let i = 0; i < length; i++) {
    password += allowedChars[randomValues[i] % allowedChars.length];
}

Asynchronously hashes the password, constructs the HIBP API request, parses the response, and triggers UI updates if a breach is detected.

• External Dependency: https://api.pwnedpasswords.com/range/{prefix}
• Error Handling: Implements try/catch to gracefully fail if the API is unreachable, ensuring the application remains functional even if offline.

Converts a plaintext string into a hexadecimal SHA-1 hash utilizing the browser's native cryptographic module.

• Performance Note: Operations are executed using ArrayBuffer and DataView for maximum memory efficiency, avoiding performance penalties during rapid keystrokes.

CyberGuard's architecture is fundamentally built upon the principle of Zero Trust regarding user input.

To verify if a password is compromised without revealing it, we utilize the HIBP K-Anonymity model.

1. Local Hashing: The plaintext password (e.g., hunter2) is hashed locally to f3bbbd66a63d4bf1747940578ec3d0103530e21d.
2. Prefix Transmission: Only the first 5 characters (f3bbb) are sent over the network.
3. Anonymity Set: The server responds with every known compromised hash that begins with f3bbb (typically hundreds of hashes).
4. Local Matching: The client searches the returned list for the suffix (d66a63...).

Why this matters: The server never receives the plaintext password. Furthermore, even the hash is protected. Because hundreds of passwords share the same 5-character prefix, the server mathematically cannot determine which specific password within that anonymity set the user is inquiring about.

Many beginner security tools use Math.random() to generate passwords. This is a severe vulnerability, as the pseudo-random number generator (PRNG) state can be predicted. CyberGuard strictly enforces the use of window.crypto.getRandomValues(), which interfaces with the operating system's hardware-based entropy pool (e.g., /dev/urandom on Unix), ensuring cryptographically secure outputs.

Because CyberGuard processes all logic client-side, its backend scalability profile is theoretically infinite. The server's only responsibility is delivering three static files (HTML, CSS, JS).

• Bandwidth: The total initial payload is under 20KB.
• Compute: Zero backend CPU utilization required for password hashing or analysis.
• API Limits: The HIBP API handles millions of requests globally. By implementing a 500ms debounce timer on input events, we prevent rapid-fire requests, drastically reducing API consumption and eliminating the risk of client-side rate limiting.

For massive deployments, CyberGuard can be placed behind a Content Delivery Network (CDN) like Cloudflare or AWS CloudFront to ensure global, low-latency availability.

The system is designed to be easily configurable via CSS Custom Properties and Javascript constants.

Modify the :root pseudo-class in style.css to completely alter the application's appearance.

:root {
    --bg-color: #0f172a;       /* Main background */
    --card-bg: #1e293b;        /* Surface color */
    --accent: #3b82f6;         /* Primary brand color */
    
    /* State Colors */
    --strength-weak: #ef4444;  /* Red */
    --strength-medium: #f59e0b;/* Yellow/Orange */
    --strength-strong: #10b981;/* Green */
}

To adjust the bounds of the password generator slider, modify the HTML attributes in index.html:

<input type="range" id="lengthSlider" min="8" max="128" value="16">

To modify how quickly the breach API is queried after a user stops typing, adjust the timeout value in script.js:

// Change 500 to 1000 for a 1-second delay
pwnedCheckTimeout = setTimeout(() => {
    checkPwnedPassword(password);
}, 500); 

Ensuring the reliability of a security tool is paramount. While automated test suites (e.g., Jest or Cypress) can be integrated later, the following manual test vectors must be validated during deployment.

1. Enter the password password123.
2. Wait 500ms for the debounce timer.
3. Expected Result: A red warning box should appear stating the password has been found in millions of breaches.
4. Open browser DevTools (Network Tab) and verify that the request made to api.pwnedpasswords.com/range/ only contains the 5-character prefix of the SHA-1 hash, NOT the plaintext string.

1. Uncheck "Lowercase", "Numbers", and "Symbols". Keep "Uppercase" checked.
2. Set length slider to 10.
3. Click "Generate".
4. Expected Result: A string of exactly 10 uppercase letters (e.g., XKQMPLWZRT).

We welcome contributions from the security and development community. To contribute to CyberGuard:

1. Fork the repository on GitHub.
2. Create a feature branch: git checkout -b feature/AdvancedEntropy
3. Commit your changes: Follow conventional commits (e.g., feat: integrate zxcvbn library).
4. Push to the branch: git push origin feature/AdvancedEntropy
5. Open a Pull Request: Detail the changes made, the problem solved, and any security implications of the new code.

• Maintain zero dependencies. Do not introduce NPM packages for frontend execution unless compiling via a build step (which must be proposed and approved first).
• All asynchronous operations must be handled with async/await and try/catch blocks.
• Ensure cross-browser compatibility for DOM manipulations.

This project is licensed under the MIT License.

MIT License

Copyright (c) 2026 TheOrionGD

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Q: Does CyberGuard store or log my passwords?
A: No. CyberGuard is a fully client-side application. Your passwords never leave your device. The application does not contain any telemetry, tracking, or database connection logic.

Q: How does the breach detection work if my password isn't sent to a server?
A: We use the K-Anonymity privacy model. Your password is mathematically scrambled (hashed) on your machine. We only send a tiny fragment (the first 5 characters) of that scrambled hash to the API. The API returns thousands of known breaches matching that fragment, and your browser searches that local list.

Q: Can I use the generated passwords for high-security accounts (e.g., banking, crypto wallets)?
A: Yes. The password generator relies on the window.crypto.getRandomValues() API, which is specifically designed by browser vendors to provide cryptographically secure pseudorandom numbers suitable for high-security key generation.

Q: Why does the breach check delay slightly while I'm typing?
A: This is intentional. A 500-millisecond "debounce" timer prevents the application from making unnecessary API requests for every single keystroke, which would cause lag and potentially result in API rate-limiting.

Q: Can I host this internally for my organization?
A: Absolutely. Because it consists entirely of static files, you can place the source code on any internal web server. The HIBP API integration requires external internet access to function, but the core entropy analysis and generation tools will work completely offline.