SafeLink-AI is an intelligent, AI-powered URL safety scanner designed to protect users from malicious and phishing websites. By leveraging advanced machine learning techniques, specifically a pre-trained XGBoost classifier, the system analyzes various features extracted from URLs in real-time to determine their safety status. It provides a robust backend API for seamless integration into web applications, ensuring a secure browsing experience against online threats.
- Real-time URL Scanning: Instantly checks URLs for potential threats via a high-performance API.
- Machine Learning Core: Utilizes a pre-trained XGBoost model (
XGBoostClassifier.pickle) for high accuracy in classifying URLs as safe or malicious. - Comprehensive Feature Extraction: Employs a robust set of URL features (e.g., domain properties, IP presence, URL length, random domain detection) implemented in
URLFeatureExtraction.pyto identify suspicious patterns. - Scalable Backend: Built with FastAPI, providing a modern, fast, and asynchronous API that can handle concurrent requests efficiently.
- CORS Support: Configured for seamless integration with various frontend applications (e.g., React/Vite).
- Developer-Friendly API: Provides a clear and well-documented API endpoint for quick adoption by client applications.
The SafeLink-AI project is built using a combination of powerful languages, frameworks, and tools:
(Python Web Framework)
(Machine Learning Library)
- Pydantic
- NumPy
- Uvicorn (ASGI server)
- ESLint
Before you begin, ensure you have the following installed on your system:
- Python 3.8+: For running the backend API.
- Node.js & npm (or yarn): For any potential frontend development or JavaScript tooling (like ESLint).
pip: Python package installer.git: For cloning the repository.
While a requirements.txt file is not explicitly present in the provided project structure, the following Python packages are necessary for the backend to function. You will need to create this file in the back-end/ directory:
fastapi
uvicorn
pydantic
numpy
scikit-learn # Often a dependency for ML models even if not directly used for XGBoost
xgboostFollow these steps to get your SafeLink-AI instance up and running locally.
First, clone the SafeLink-AI repository to your local machine:
git clone https://github.com/anan5093/SafeLink-AI.git
cd SafeLink-AIThe backend is developed using Python and FastAPI.
cd back-endCreate a file named requirements.txt in the back-end/ directory and populate it with the dependencies listed in the Prerequisites & Dependencies section.
python -m venv venv
source venv/bin/activate # On Windows: .\venv\Scripts\activateInstall all required Python packages:
pip install -r requirements.txtWhile main.py directly defines CORS origins, for more flexible configuration or for sensitive data like API keys, you can use a .env file in the project root (SafeLink-AI/.env). For example, you might add:
# .env (example)
ALLOWED_ORIGINS="http://localhost:5173,https://your-frontend-domain.com"
API_PORT=8000You would then need to integrate python-dotenv into main.py to load these variables.
Start the FastAPI application using Uvicorn:
uvicorn main:app --host 0.0.0.0 --port 8000 --reloadThe API will now be accessible at http://localhost:8000.
The presence of eslint.config.js and Node.js in the technical details, along with CORS origins for http://localhost:5173 (Vite/React) and https://anan5093.github.io (GitHub Pages), suggests that a frontend client is intended or exists externally.
If you have a frontend client that consumes this API:
- Navigate to your frontend project directory.
- Install its dependencies (e.g.,
npm installoryarn install). - Start your frontend development server (e.g.,
npm run dev).- Important: Ensure your frontend's origin is listed in the
originsarray inback-end/main.pyfor CORS to work correctly.
- Important: Ensure your frontend's origin is listed in the
The SafeLink-AI backend exposes a RESTful API for URL scanning.
- Base URL:
http://localhost:8000(or your deployed domain) - Endpoint:
/predict - Method:
POST
Send a JSON object with a url string field:
{
"url": "https://example.com/malicious-link"
}To test the API, you can use curl from your terminal:
curl -X POST \
http://localhost:8000/predict \
-H 'Content-Type: application/json' \
-d '{
"url": "https://www.google.com"
}'A response for a safe URL might look like:
{
"prediction": 0,
"prediction_label": "Safe",
"prediction_score": 0.99
}And for a malicious URL:
{
"prediction": 1,
"prediction_label": "Malicious",
"prediction_score": 0.85
}import requests
import json
api_url = "http://localhost:8000/predict"
test_url = "http://phishing-site.com/login" # Replace with a real (or simulated) URL for testing
payload = {"url": test_url}
headers = {"Content-Type": "application/json"}
try:
response = requests.post(api_url, data=json.dumps(payload), headers=headers)
response.raise_for_status() # Raise an exception for HTTP errors
result = response.json()
print(f"URL: {test_url}")
print(f"Prediction: {result['prediction_label']} (Score: {result['prediction_score']:.2f})")
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")FastAPI automatically generates interactive API documentation (Swagger UI and ReDoc). Once the server is running, you can access them at:
- Swagger UI:
http://localhost:8000/docs - ReDoc:
http://localhost:8000/redoc
The backend is configured to handle CORS for specific origins, defined in back-end/main.py. You can modify the origins list to allow requests from your frontend application(s):
# back-end/main.py
origins = [
"http://localhost:5173", # React (Vite) development server
"http://localhost",
"http://127.0.0.1:5173",
"https://anan5093.github.io", # Production frontend (GitHub Pages)
# Add your frontend URLs here, e.g., "https://your-frontend-domain.com"
]
app.add_middleware(
CORSMiddleware,
allow_origins=origins,
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)We welcome contributions to SafeLink-AI! If you'd like to contribute, please follow these guidelines:
- Fork the Repository: Start by forking the
anan5093/SafeLink-AIrepository to your GitHub account. - Clone Your Fork: Clone your forked repository to your local machine.
git clone https://github.com/YOUR_USERNAME/SafeLink-AI.git cd SafeLink-AI - Create a New Branch: Create a new branch for your feature or bug fix.
git checkout -b feature/your-feature-name
- Make Changes: Implement your changes, ensuring code quality and adherence to existing coding styles.
- For Python code, follow PEP 8.
- For JavaScript (if adding frontend or JS tooling), ensure
eslint.config.jsrules are respected.
- Test Your Changes: Thoroughly test your changes to ensure they work as expected and don't introduce regressions.
- Commit Your Changes: Write clear and concise commit messages.
git commit -m "feat: Add new feature for X" - Push to Your Fork: Push your new branch to your forked repository.
git push origin feature/your-feature-name
- Create a Pull Request: Open a pull request from your branch to the
mainbranch of the originalanan5093/SafeLink-AIrepository. Provide a detailed description of your changes.
The repository uses GitHub Actions (.github/workflows/main.yml) for continuous integration. Ensure your contributions pass any defined CI checks.
This project currently does not have an explicit license specified. This means that, by default, all rights are reserved by the copyright holder (anan5093).
Recommendation: It is highly recommended to add an open-source license (e.g., MIT, Apache 2.0, GPL) to encourage community contributions and clarify usage rights. You can do this by adding a LICENSE file to the root of the repository.
- Special thanks to the developers of FastAPI, Uvicorn, XGBoost, and the broader open-source community for providing powerful tools and libraries that made this project possible.
- The URL feature extraction logic is inspired by common techniques used in phishing detection research.