ClickShield

KO | EN

gitlite — search

#python #cli #golang #ai #javascript #mcp #go #llm #tailwindcss #mcp-server #study-material #bot

★ 13 Open GitHub ↗

🛡️ ClickShield is a modern, user-friendly web application that helps users identify potentially malicious websites and phishing attempts. Built with React and TypeScript, it leverages Google's Safe Browsing API to provide real-time threat analysis and comprehensive security reports.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
  <img src="frontend/src/assets/clickshield-banner.png" alt="ClickShield Banner - Website Safety and Phishing Detection" width="100%" style="max-width:800px; border-radius:18px; margin:18px 0; box-shadow:0 4px 32px #00d4aa22;"/>
  <p>
    <img src="https://img.shields.io/badge/React-18.2.0-61dafb?style=flat-square&logo=react" alt="React" />
    <img src="https://img.shields.io/badge/TypeScript-5.3-3178c6?style=flat-square&logo=typescript" alt="TypeScript" />
    <img src="https://img.shields.io/badge/Node.js-18+-339933?style=flat-square&logo=node.js" alt="Node.js" />
    <img src="https://img.shields.io/badge/Google%20Safe%20Browsing-API-blue?style=flat-square&logo=google" alt="Google Safe Browsing" />
    <img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="MIT License" />
  </p>
  <p>
    <a href="#features"><img src="https://api.iconify.design/mdi:star-four-points.svg?color=%23f59e0b" width="18"/> Features</a>
    &nbsp;•&nbsp;
    <a href="#installation"><img src="https://api.iconify.design/mdi:package-down.svg?color=%23ef4444" width="18"/> Installation</a>
    &nbsp;•&nbsp;
    <a href="#usage"><img src="https://api.iconify.design/mdi:book-open-page-variant.svg?color=%238b5cf6" width="18"/> Usage</a>
    &nbsp;•&nbsp;
    <a href="#contributing"><img src="https://api.iconify.design/mdi:github.svg?color=%233b82f6" width="18"/> Contributing</a>
  </p>
</div>

---

## <img src="https://api.iconify.design/mdi:eye.svg?color=%2300d4aa" width="24"/> Overview

ClickShield is a modern, user-friendly web application that helps users identify potentially malicious websites and phishing attempts. Built with React and TypeScript, it leverages Google's Safe Browsing API to provide real-time threat analysis and comprehensive security reports.

## <img src="https://api.iconify.design/mdi:star-four-points.svg?color=%23f59e0b" width="24"/> Features

### <img src="https://api.iconify.design/mdi:flash.svg?color=%23f59e0b" alt="Lightning" width="20" height="20"> Core Features

- <img src="https://github.com/tbhvishal/ClickShield/blob/main/frontend/src/assets/500x500.png?raw=true" width="18"/> **Real-time Threat Detection**: Instant analysis using Google's Safe Browsing API
- <img src="https://api.iconify.design/mdi:file-chart.svg?color=%233b82f6" width="18"/> **Comprehensive Reports**: Detailed security analysis with threat intelligence
- <img src="https://api.iconify.design/mdi:history.svg?color=%238b5cf6" width="18"/> **Scan History**: Track and review previous security scans
- <img src="https://api.iconify.design/mdi:certificate.svg?color=%23ef4444" width="18"/> **SSL Verification**: Check website certificate validity
- <img src="https://api.iconify.design/mdi:file-pdf-box.svg?color=%23f59e0b" width="18"/> **PDF Reports**: Export professional security reports
- <img src="https://api.iconify.design/mdi:weather-night.svg?color=%236b7280" width="18"/> **Dark Mode**: Modern UI with dark/light theme support

### <img src="https://api.iconify.design/mdi:cellphone-link.svg?color=%233b82f6" alt="Mobile" width="20" height="20"> User Experience

- <img src="https://api.iconify.design/mdi:flash.svg?color=%23f59e0b" width="18"/> **Lightning Fast**: Instant results with optimized performance
- <img src="https://api.iconify.design/mdi:responsive.svg?color=%238b5cf6" width="18"/> **Responsive Design**: Works perfectly on all devices
- <img src="https://api.iconify.design/mdi:accessibility.svg?color=%2310b981" width="18"/> **Accessibility**: WCAG compliant with screen reader support

## <img src="https://api.iconify.design/mdi:code-braces.svg?color=%233b82f6" width="24"/> Tech Stack

### <img src="https://api.iconify.design/mdi:monitor-dashboard.svg?color=%233b82f6" alt="Frontend" width="20" height="20"> Frontend
- <img src="https://api.iconify.design/logos:react.svg" width="18"/> **React 18** - Modern React with hooks and concurrent features
- <img src="https://api.iconify.design/logos:typescript-icon.svg" width="18"/> **TypeScript** - Type-safe JavaScript development
- <img src="https://api.iconify.design/logos:vitejs.svg" width="18"/> **Vite** - Fast build tool and development server
- <img src="https://api.iconify.design/logos:tailwindcss-icon.svg" width="18"/> **Tailwind CSS** - Utility-first CSS framework
- <img src="https://api.iconify.design/mdi:motion.svg?color=%23f59e0b" width="18"/> **Framer Motion** - Smooth animations and transitions

### <img src="https://api.iconify.design/mdi:server.svg?color=%2310b981" alt="Backend" width="20" height="20"> Backend
- <img src="https://api.iconify.design/logos:nodejs-icon.svg" width="18"/> **Node.js** - JavaScript runtime
- <img src="https://img.icons8.com/?size=100&id=2ZOaTclOqD4q&format=png&color=000000" width="18"/> **Express.js** - Web application framework
- <img src="https://api.iconify.design/logos:google-icon.svg" width="18"/> **Google Safe Browsing API** - Threat intelligence

### <img src="https://api.iconify.design/mdi:tools.svg?color=%236b7280" alt="Tools" width="20" height="20"> Development Tools
- <img src="https://api.iconify.design/logos:eslint.svg" width="18"/> **ESLint** - Code linting
- <img src="https://api.iconify.design/logos:git-icon.svg" width="18"/> **Git** - Version control
- <img src="https://api.iconify.design/logos:npm-icon.svg" width="18"/> **NPM** - Package management

## <img src="https://api.iconify.design/mdi:package-down.svg?color=%23ef4444" width="24"/> Installation

### <img src="https://api.iconify.design/mdi:alert-decagram.svg?color=%23ef4444" width="20"/> Prerequisites

Before you begin, ensure you have the following installed:
- <img src="https://api.iconify.design/logos:nodejs-icon.svg" alt="Node.js" width="16" height="16"> **Node.js** (version 18 or higher)
- <img src="https://api.iconify.design/logos:npm-icon.svg" width="16"/> **npm** or <img src="https://api.iconify.design/logos:yarn.svg" width="16"/> **yarn** package manager
- <img src="https://api.iconify.design/logos:google-icon.svg" width="16"/> **Google Safe Browsing API Key**

### <img src="https://api.iconify.design/mdi:clipboard-list.svg?color=%23f59e0b" width="20"/> Setup Instructions

1. **<img src="https://api.iconify.design/mdi:download.svg?color=%233b82f6" width="16"/> Clone the repository**
  ```bash
  git clone https://github.com/tbhvishal/ClickShield.git
  cd ClickShield
  ```

2. **<img src="https://api.iconify.design/mdi:file-document.svg?color=%23f59e0b" width="16"/> Configure environment variables**
  ```bash
  # Copy the example environment file
  cp .env.example .env
  
  # Edit .env and add your Google Safe Browsing API key
  # GOOGLE_SAFE_BROWSING_API_KEY=your_api_key_here
  ```
  
  **Important:** For local development, ensure your `.env` file contains:
  ```env
  GOOGLE_SAFE_BROWSING_API_KEY=your_api_key_here
  VITE_BACKEND_API_URL=http://localhost:8001
  ```
  
  **Note:** Port numbers (8001, 5173) and other non-sensitive configs are defined in `config.ts` at the root.

3. **<img src="https://api.iconify.design/mdi:check-circle.svg?color=%238b5cf6" width="16"/> Verify your setup (Optional but Recommended)**
  ```bash
  npm run verify
  ```
  *This will check:*
  - ✓ Node.js version (18+)
  - ✓ `.env` file exists and is configured correctly
  - ✓ All required dependencies are installed
  - ✓ Project structure is correct
  
  **If all checks pass ✅, you're ready to go!**

4. **<img src="https://api.iconify.design/mdi:rocket-launch.svg?color=%2310b981" width="16"/> Start the application in development mode**
  ```bash
  npm start
  ```
  *This will:*
  - Install all dependencies (frontend + backend)
  - Build the project
  - Start backend server on `http://localhost:8001`
  - Start frontend dev server on `http://localhost:5173`
  - Open your browser automatically

---

## <img src="https://api.iconify.design/mdi:cloud.svg?color=%233b82f6" width="24"/> Production & Cloud Deployment

### <img src="https://api.iconify.design/mdi:information.svg?color=%23f59e0b" width="20"/> Environment Configuration

**For Local Development (`.env`):**
```env
GOOGLE_SAFE_BROWSING_API_KEY=your_api_key_here
VITE_BACKEND_API_URL=http://localhost:8001  # Important: Must be set for local dev
```

**Configuration File (`config.ts`):**
- Port numbers (8001, 5173) and other non-sensitive settings
- Committed to version control
- Easy to modify without touching `.env`

**For Production/Vercel (Vercel Dashboard):**
- Set `GOOGLE_SAFE_BROWSING_API_KEY` in Vercel environment variables
- Leave `VITE_BACKEND_API_URL` empty or unset - production uses relative URLs

### <img src="https://api.iconify.design/mdi:cloud-upload.svg?color=%2310b981" width="20"/> Deploying to Cloud Providers

1. **Install all dependencies (in CI/CD or cloud build step):**
  ```bash
  npm run install:all
  ```
2. **Build the project for production:**
  ```bash
  npm run build
  ```
  - This builds the frontend (Vite) to `frontend/dist/` and the backend (TypeScript) to `backend/dist/`.
  
3. **Configure environment variables in your cloud provider:**
   - Set `GOOGLE_SAFE_BROWSING_API_KEY` in your cloud dashboard
   - Leave `VITE_BACKEND_API_URL` empty (or don't set it)

4. **Deploy:**
   - **<img src="https://api.iconify.design/logos:vercel-icon.svg" width="16"/> Vercel**: Use the included `vercel.json` configuration
   - **<img src="https://api.iconify.design/logos:aws.svg" width="16"/> Other platforms**: Serve `frontend/dist/` as static files and run backend from `backend/dist/`

**⚠️ Important:** 
- **Never use `npm start` for production** - it's for local development only
- Always use `npm run build` for production builds
- Keep one `.env` file in the root directory for all configurations

### <img src="https://api.iconify.design/logos:google-icon.svg" width="20"/> Google Safe Browsing API Setup

- Visit [Google Cloud Console](https://console.cloud.google.com/)
- Create a new project or select existing one
- Enable the Safe Browsing API
- Create credentials (API Key)
- Add your API key to the root `.env` file:
  ```
  GOOGLE_SAFE_BROWSING_API_KEY=your_api_key_here
  ```

## <img src="https://api.iconify.design/mdi:book-open-page-variant.svg?color=%238b5cf6" width="24"/> Usage

### <img src="https://api.iconify.design/mdi:play-circle.svg?color=%2310b981" width="20"/> Getting Started

1. **<img src="https://api.iconify.design/mdi:web.svg?color=%233b82f6" width="16"/> Open your browser** and navigate to `http://localhost:5173`
2. **<img src="https://api.iconify.design/mdi:cursor-text.svg?color=%23f59e0b" width="16"/> Enter a URL** in the input field
3. **<img src="https://api.iconify.design/mdi:magnify.svg?color=%23ef4444" width="16"/> Click "Scan Website"** to analyze
4. **<img src="https://api.iconify.design/mdi:eye.svg?color=%238b5cf6" width="16"/> Review results** and security recommendations

### <img src="https://api.iconify.design/mdi:help-circle.svg?color=%23f59e0b" width="20"/> How It Works

1. **<img src="https://api.iconify.design/mdi:keyboard.svg?color=%233b82f6" width="16"/> URL Submission**: User enters a website URL
2. **<img src="https://api.iconify.design/mdi:lightning-bolt.svg?color=%23f59e0b" width="16"/> API Query**: Backend queries Google Safe Browsing API
3. **<img src="https://api.iconify.design/mdi:brain.svg?color=%238b5cf6" width="16"/> Analysis**: Advanced threat analysis and classification
4. **<img src="https://api.iconify.design/mdi:file-chart.svg?color=%2310b981" width="16"/> Report Generation**: Comprehensive security report
5. **<img src="https://api.iconify.design/mdi:download.svg?color=%23ef4444" width="16"/> PDF Export**: Optional professional PDF report

---

## <img src="https://api.iconify.design/mdi:console.svg?color=%23f59e0b" width="24"/> Available Scripts

| Command | Description |
|---------|-------------|
| `npm start` | 🚀 Install dependencies, build, and start both servers for local development |
| `npm run verify` | ✅ Verify your setup is configured correctly (recommended before first run) |
| `npm run dev:backend` | 🔧 Start only the backend server in development mode |
| `npm run dev:frontend` | 🎨 Start only the frontend server in development mode |
| `npm run install:all` | 📦 Install dependencies for root, backend, and frontend |
| `npm run build` | 🏗️ Build both frontend and backend for production |
| `npm run build:backend` | 🔨 Build only the backend |
| `npm run build:frontend` | 🎭 Build only the frontend |
| `npm run start:backend` | ▶️ Start the built backend server |
| `npm run start:frontend` | 🌐 Preview the built frontend |
| `npm run clean` | 🧹 Remove all node_modules and dist folders |

**💡 Tip:** Always run `npm run verify` after cloning the repository or changing your `.env` file to ensure everything is configured correctly!

---

## <img src="https://api.iconify.design/mdi:folder-outline.svg?color=%238b5cf6" width="24"/> Project Structure

<details>
<summary>Click to expand project structure</summary>

```
ClickShield/
├── .env                    # ⚠️ Your local environment config (DO NOT COMMIT)
├── .env.example            # Template for .env
├── config.ts               # Non-sensitive configuration (ports, etc.)
├── package.json            # Root package file
├── start.js                # Development startup script
├── verify-setup.js         # Setup verification script
├── README.md               # This file - complete documentation
├── backend/                # Backend Express API
│   ├── src/
│   │   ├── server.ts       # Server entry point
│   │   ├── app.ts          # Express app configuration
│   │   └── api/
│   │       └── checkUrl.ts # URL checking API endpoint
│   └── package.json
└── frontend/               # Frontend React app
    ├── src/
    │   ├── App.tsx         # Main app component
    │   └── components/     # React components
    └── package.json
```

</details>

---

## <img src="https://api.iconify.design/mdi:wrench.svg?color=%23ef4444" width="24"/> Troubleshooting

<details>
<summary>🚫 Blank page or "Cannot connect to server"</summary>

### Symptoms
- Page title and favicon load but content doesn't appear
- Browser console shows connection errors
- Frontend can't reach backend API

### Solution
1. **Check your `.env` file in the root directory**
   ```env
   VITE_BACKEND_API_URL=http://localhost:8001
   ```
   ⚠️ This line **MUST** be set for local development!

2. **Verify both servers are running:**
   ```bash
   # Backend should show:
   ✅ Backend server running on http://localhost:8001
   
   # Frontend should show:
   ➜  Local:   http://localhost:5173/
   ```

3. **If still not working, restart:**
   ```bash
   # Stop all servers (Ctrl+C)
   # Then run:
   npm start
   ```

</details>

<details>
<summary>🔑 "Google Safe Browsing API key not configured" error</summary>

### Solution
1. Get your API key from [Google Cloud Console](https://console.cloud.google.com/)
2. Add it to root `.env` file:
   ```env
   GOOGLE_SAFE_BROWSING_API_KEY=your_actual_key_here
   ```
3. Restart the servers

</details>

<details>
<summary>🌐 Works on Vercel but not locally (or vice versa)</summary>

### Root Cause
Different environment configurations

### Solution

**For Local Development** (`.env`):
```env
GOOGLE_SAFE_BROWSING_API_KEY=your_api_key_here
VITE_BACKEND_API_URL=http://localhost:8001  # ← REQUIRED for local!
```

**For Production/Vercel** (set in Vercel Dashboard):
- `GOOGLE_SAFE_BROWSING_API_KEY=your_api_key_here`
- `VITE_BACKEND_API_URL` should be EMPTY or not set

**Note:** Port numbers (8001, 5173) are defined in `config.ts` - no need to set them in `.env`.

</details>

<details>
<summary>📦 "Module not found" or dependency errors</summary>

### Solution
```bash
# Clean install everything
npm run clean
npm run install:all

# Or manually:
cd backend && npm install
cd ../frontend && npm install
cd ..
npm install
```

</details>

<details>
<summary>🏗️ Build fails or TypeScript errors</summary>

### Solution
```bash
# Clean and rebuild
cd backend && rm -rf dist node_modules
npm install
npm run build

cd ../frontend && rm -rf dist node_modules
npm install
npm run build
```

</details>

<details>
<summary>🔄 Changes not reflecting after update</summary>

### Solution
```bash
# Hard refresh in browser: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)

# Or clear Vite cache:
cd frontend
rm -rf node_modules/.vite
npm run dev
```

</details>

<details>
<summary>🐳 Docker setup not working</summary>

### Solution
```bash
# Make sure .env exists with proper values
cp .env.example .env
# Edit .env with your API key

# Rebuild containers
docker-compose down
docker-compose up --build
```

</details>

<details>
<summary>✅ Quick verification checks</summary>

### Verify Environment Setup

```bash
# Windows (PowerShell)
Get-Content .env | Select-String "VITE_BACKEND_API_URL"

# Mac/Linux
cat .env | grep VITE_BACKEND_API_URL
```

**Expected output for local dev:**
```
VITE_BACKEND_API_URL=http://localhost:8001
```

### Check if Servers are Running

```bash
# Check backend
curl http://localhost:8001/check-url

# Should return: {"error":"Invalid or missing URL.",...}
```

### Check Frontend can reach Backend

1. Open browser console (F12)
2. Look for this log:
   ```
   VITE_BACKEND_API_URL: http://localhost:8001
   ```
3. If it shows `undefined`, your `.env` is not configured correctly

### Check if Ports are in Use

```bash
# Windows
netstat -ano | findstr :8001
netstat -ano | findstr :5173

# Mac/Linux
lsof -i :8001
lsof -i :5173
```

</details>

<details>
<summary>🆘 Still having issues?</summary>

1. **Check the logs:**
   - Backend logs show in the terminal where you ran `npm start`
   - Frontend logs show in browser console (F12)

2. **Try a different port:**
   Update `config.ts` and `.env`:
   
   **config.ts:**
   ```typescript
   backend: 8002,  // Changed from 8001
   ```
   
   **.env:**
   ```env
   VITE_BACKEND_API_URL=http://localhost:8002
   ```

3. **Check firewall/antivirus:**
   - Allow Node.js through firewall
   - Temporarily disable antivirus to test

4. **Get help:**
   - Check [GitHub Issues](https://github.com/tbhvishal/ClickShield/issues)
   - Create a new issue with:
     - Your OS and Node.js version
     - Full error message
     - Output of `npm start`
     - Your `.env` configuration (without API key)

</details>

---

## <img src="https://api.iconify.design/mdi:api.svg?color=%233b82f6" width="24"/> API Reference

For API implementation details (endpoints, request/response shapes and error handling), see `backend/src/api/checkUrl.ts`.

---

## <img src="https://api.iconify.design/mdi:hand-heart.svg?color=%23ef4444" width="24"/> Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### <img src="https://api.iconify.design/mdi:account-group.svg?color=%2310b981" width="20"/> How to Contribute

1. **<img src="https://api.iconify.design/mdi:source-fork.svg?color=%233b82f6" width="16"/> Fork the repository**
2. **<img src="https://api.iconify.design/mdi:source-branch.svg?color=%23f59e0b" width="16"/> Create a feature branch**
   ```bash
   git checkout -b feature/amazing-feature
   ```

3. <img src="https://api.iconify.design/mdi:source-commit.svg?color=%23ef4444" width="18"/> **Commit your changes**
  ```bash
  git commit -m 'Add amazing feature'
  ```
4. <img src="https://api.iconify.design/mdi:upload.svg?color=%238b5cf6" width="18"/> **Push to the branch**
  ```bash
  git push origin feature/amazing-feature
  ```
5. <img src="https://api.iconify.design/mdi:source-pull.svg?color=%2310b981" width="18"/> **Open a Pull Request**

### <img src="https://api.iconify.design/mdi:bug.svg?color=%23ef4444" width="20"/> Reporting Issues

- <img src="https://api.iconify.design/mdi:bug-check-outline.svg?color=%23ef4444" width="18"/> **Bug Reports**: [GitHub Issues](https://github.com/tbhvishal/ClickShield/issues)
- <img src="https://api.iconify.design/mdi:lightbulb-on-outline.svg?color=%23f59e0b" width="18"/> **Feature Requests**: [GitHub Issues](https://github.com/tbhvishal/ClickShield/issues)

## <img src="https://api.iconify.design/mdi:heart.svg?color=%23ef4444" width="24"/> Support

If you find ClickShield helpful, please consider:

- **<img src="https://api.iconify.design/mdi:account-heart.svg?color=%233b82f6" width="16"/> Following the developer: [@tbhvishal](https://github.com/tbhvishal))**
- **<img src="https://api.iconify.design/mdi:star.svg?color=%23f59e0b" width="16"/> Starring** the repository
- **<img src="https://api.iconify.design/mdi:share-variant.svg?color=%233b82f6" width="16"/> Sharing** with others
- **<img src="https://api.iconify.design/mdi:handshake.svg?color=%2310b981" width="16"/> Contributing** to the project

## <img src="https://api.iconify.design/mdi:scale-balance.svg?color=%2310b981" width="24"/> License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

<div align="center">
  <p><strong>Made with <img src="https://api.iconify.design/mdi:heart.svg?color=%23ef4444" width="16"/> by Vishal Sharma</strong></p>

---

<div align="center">
  <p><strong><img src="https://github.com/tbhvishal/ClickShield/blob/main/frontend/src/assets/500x500.png?raw=true" width="24"/> Stay Safe Online with ClickShield <img src="https://github.com/tbhvishal/ClickShield/blob/main/frontend/src/assets/500x500.png?raw=true" width="24"/></strong></p>
  <p><em>Advanced threat detection for a safer internet experience</em></p>
</div>

ClickShield

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README