HumanShield

HumanShield is a cybersecurity engineering platform designed to detect social engineering techniques, conduct safe phishing-awareness simulations, evaluate human security risk, and generate security awareness reports.

Project Objectives

• Detect social engineering techniques in suspicious messages
• Analyze phishing URLs and impersonation attempts
• Run permission-based phishing-awareness simulations
• Track safe participant interactions
• Calculate explainable human-risk scores
• Provide security awareness training
• Generate professional security reports

Planned Technology Stack

• Frontend: Next.js, TypeScript, Tailwind CSS
• Backend: Python, FastAPI
• Database: PostgreSQL
• Analysis Engine: Python
• Authentication: JWT and role-based access control
• Deployment: Docker Compose
• Testing: Pytest and frontend testing tools

Project Status

Currently under development.

Local development

HumanShield reads backend configuration from a .env file in the project root. The file is intentionally ignored by Git and must not be committed.

1. Copy .env.example to .env:

   Copy-Item .env.example .env

2. Replace every placeholder in .env with values for your local environment:

   • DATABASE_URL is required and must contain a valid SQLAlchemy PostgreSQL connection URL for an existing HumanShield database.
   • JWT_SECRET_KEY is required and must be a stable, securely generated secret. Changing it invalidates existing access tokens.
   • URLHAUS_AUTH_KEY is optional for login, but is required for live URLhaus reputation checks.

3. Ensure PostgreSQL is running, then start FastAPI from the project root:

   .\.venv\Scripts\python.exe -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000

4. Verify the backend before starting or using the frontend:

   Invoke-RestMethod http://127.0.0.1:8000/health

   The response should report status as healthy. If FastAPI exits during startup, check the backend console and confirm that DATABASE_URL contains valid local database credentials.

The Next.js frontend runs at http://localhost:3000 and calls the FastAPI backend at http://127.0.0.1:8000 by default during local development. To use a different backend origin, copy frontend/.env.example to frontend/.env.local, set NEXT_PUBLIC_API_BASE_URL, and restart Next.js. This is a browser-visible setting; never place secrets in a NEXT_PUBLIC_* variable.

Ethical Use

HumanShield is intended only for authorized cybersecurity awareness training and defensive security research.

The platform will not collect real passwords or support unauthorized phishing campaigns.