{"id":50937498,"url":"https://github.com/suspecting/cloudsec-auditor","last_synced_at":"2026-06-17T11:00:23.698Z","repository":{"id":365235858,"uuid":"1271171967","full_name":"Suspecting/CloudSec-Auditor","owner":"Suspecting","description":"CloudSec Auditor is a React + FastAPI AWS security misconfiguration scanner with mock scan mode, risk scoring, findings explorer, and timestamped JSON, HTML, and Markdown report exports.","archived":false,"fork":false,"pushed_at":"2026-06-16T13:28:16.000Z","size":13630,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T14:11:59.615Z","etag":null,"topics":["aws-audit","aws-security","cloud-security","cybersecurity","misconfiguration-scanner","python","react","risk-scoring","security-tools","tailwindcss","vite"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Suspecting.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-16T12:02:20.000Z","updated_at":"2026-06-16T13:29:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Suspecting/CloudSec-Auditor","commit_stats":null,"previous_names":["suspecting/cloudsec-auditor"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Suspecting/CloudSec-Auditor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suspecting%2FCloudSec-Auditor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suspecting%2FCloudSec-Auditor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suspecting%2FCloudSec-Auditor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suspecting%2FCloudSec-Auditor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Suspecting","download_url":"https://codeload.github.com/Suspecting/CloudSec-Auditor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suspecting%2FCloudSec-Auditor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34445186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-audit","aws-security","cloud-security","cybersecurity","misconfiguration-scanner","python","react","risk-scoring","security-tools","tailwindcss","vite"],"created_at":"2026-06-17T11:00:16.025Z","updated_at":"2026-06-17T11:00:23.680Z","avatar_url":"https://github.com/Suspecting.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CloudSec Auditor\n\n**CloudSec Auditor** is a local-first AWS security misconfiguration scanner built with a **React + Vite frontend** and **FastAPI backend**. It audits AWS cloud security posture through a local read-only AWS CLI profile, calculates a risk score, prioritizes findings, and generates timestamped **JSON, HTML, and Markdown** reports.\n\nThe project is designed for defensive cloud security learning, portfolio demonstration, interview explanation, and future extension into real AWS read-only auditing using `boto3`.\n\n---\n\n## Author\n\n**Prakhar Shakya**\nB.Tech CSE — Cybersecurity\nLloyd Institute of Engineering and Technology, Greater Noida\nDelhi NCR, India\n\n* GitHub: [@Suspecting](https://github.com/Suspecting)\n* LinkedIn: [@Prakhar Shakya](https://www.linkedin.com/in/shakyaprakhar/)\n\n---\n\n## Project Overview\n\nCloudSec Auditor helps identify and present common cloud security misconfigurations in a clean dashboard format. The current version supports **real AWS read-only mode** using a local AWS CLI profile.\n\nIt simulates AWS security checks across IAM, S3, EC2, CloudTrail, encryption, and network exposure areas, then generates audit-ready output with evidence and remediation guidance.\n\n---\n\n## Key Features\n\n* Modern AWS-style security dashboard\n* FastAPI backend with structured scan APIs\n* React frontend with premium dark cybersecurity UI\n* Real AWS read-only scan mode using a local AWS CLI profile\n* Risk score calculation based on severity\n* Prioritized findings with evidence and remediation\n* Findings Explorer with:\n\n  * Severity filters\n  * Service filters\n  * Search functionality\n  * Clear filters option\n  * Severity summary cards\n* Backend health and API version indicator\n* Timestamped report export system\n* Latest report viewer from frontend\n* JSON, HTML, and Markdown report generation\n* Report metadata survives page refresh\n* Helper scripts for local setup and development\n* Local-first security design\n\n---\n\n## Tech Stack\n\n### Frontend\n\n* React\n* Vite\n* Tailwind CSS\n* Framer Motion\n* Axios\n* Lucide React\n\n### Backend\n\n* Python\n* FastAPI\n* Uvicorn\n* Pydantic\n* pathlib\n* boto3 active for real AWS read-only mode\n\n---\n\n## Project Structure\n\n```text\nCloudSec-Auditor/\n├── backend/\n│   ├── core/\n│   │   ├── __init__.py\n│   │   ├── config.py\n│   │   ├── error_handlers.py\n│   │   └── logging_config.py\n│   │\n│   ├── routes/\n│   │   ├── __init__.py\n│   │   ├── report_routes.py\n│   │   ├── scan_routes.py\n│   │   └── status_routes.py\n│   │\n│   ├── schemas/\n│   │   ├── __init__.py\n│   │   └── response_models.py\n│   │\n│   ├── cloudsec/\n│   │   ├── __init__.py\n│   │   ├── cloudtrail_checks.py\n│   │   ├── ec2_checks.py\n│   │   ├── iam_checks.py\n│   │   ├── mock_data.py\n│   │   ├── report_generator.py\n│   │   ├── risk_score.py\n│   │   └── s3_checks.py\n│   │\n│   ├── main.py\n│   └── requirements.txt\n│\n├── desktop/\n│   └── frontend/\n│       ├── public/\n│       ├── src/\n│       │   ├── App.jsx\n│       │   ├── index.css\n│       │   └── main.jsx\n│       ├── package.json\n│       └── vite.config.js\n│\n├── reports/\n│   └── .gitkeep\n│\n├── screenshots/\n├── scripts/\n│   ├── clean_reports.sh\n│   ├── run_backend.sh\n│   ├── run_frontend.sh\n│   ├── setup_backend.sh\n│   └── setup_frontend.sh\n│\n├── .gitignore\n└── README.md\n```\n\n---\n\n## How It Works\n\n```text\nUser clicks Scan\n        ↓\nReact frontend calls FastAPI backend\n        ↓\nBackend returns real AWS read-only security findings\n        ↓\nRisk score is calculated\n        ↓\nDashboard updates with findings\n        ↓\nReports are generated\n        ↓\nLatest JSON, HTML, and Markdown reports become available\n```\n\n---\n\n## Security Checks Covered\n\nImplemented read-only checks include:\n\n* S3 public bucket exposure\n* S3 bucket default encryption\n* IAM users without MFA\n* IAM access key age\n* EC2 SSH exposure to `0.0.0.0/0`\n* EBS encryption status\n* CloudTrail audit visibility\n* Passed informational checks\n\nEach finding includes:\n\n* Service\n* Severity\n* Status\n* Resource\n* Region\n* Category\n* Evidence\n* Remediation guidance\n\n---\n\n## Quick Start with Helper Scripts\n\nCloudSec Auditor includes helper scripts for easier local setup and development.\n\n### Backend Setup\n\n```bash\n./scripts/setup_backend.sh\n```\n\n### Run Backend\n\n```bash\n./scripts/run_backend.sh\n```\n\nThe backend runs at:\n\n```text\nhttp://127.0.0.1:8000\n```\n\nFastAPI docs:\n\n```text\nhttp://127.0.0.1:8000/docs\n```\n\n### Frontend Setup\n\nOpen another terminal:\n\n```bash\n./scripts/setup_frontend.sh\n```\n\n### Run Frontend\n\n```bash\n./scripts/run_frontend.sh\n```\n\nThe frontend runs at:\n\n```text\nhttp://localhost:5173\n```\n\n### Clean Generated Reports\n\n```bash\n./scripts/clean_reports.sh\n```\n\n---\n\n## Manual Backend Setup\n\nOpen a terminal in the project root:\n\n```bash\ncd backend\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\nuvicorn main:app --reload --host 127.0.0.1 --port 8000\n```\n\nBackend runs at:\n\n```text\nhttp://127.0.0.1:8000\n```\n\nFastAPI docs:\n\n```text\nhttp://127.0.0.1:8000/docs\n```\n\n---\n\n## Manual Frontend Setup\n\nOpen another terminal:\n\n```bash\ncd desktop/frontend\nnpm install\nnpm run dev\n```\n\nFrontend runs at:\n\n```text\nhttp://localhost:5173\n```\n\n---\n\n## API Endpoints\n\n| Endpoint                       | Method | Purpose                                         |\n| ------------------------------ | -----: | ----------------------------------------------- |\n| `/`                            |    GET | Root API information                            |\n| `/health`                      |    GET | Basic backend health check                      |\n| `/api/status`                  |    GET | Backend status, version, mode, and report count |\n| `/api/reports/latest`          |    GET | Returns latest report metadata                  |\n| `/api/reports/latest/html`     |    GET | Opens latest HTML report                        |\n| `/api/reports/latest/json`     |    GET | Opens latest JSON report                        |\n| `/api/reports/latest/markdown` |    GET | Opens latest Markdown report                    |\n\n---\n\n## Report Generation\n\nCloudSec Auditor generates timestamped report files inside the `reports/` folder.\n\nExample output:\n\n```text\ncloudsec_report_2026-06-16_14-35-22.json\ncloudsec_report_2026-06-16_14-35-22.html\ncloudsec_report_2026-06-16_14-35-22.md\n```\n\nReports are ignored by Git to keep the repository clean. The folder structure is preserved using:\n\n```text\nreports/.gitkeep\n```\n\n---\n\n## Screenshots\n\n### Hero Dashboard\n\n![Hero Dashboard](screenshots/hero-dashboard.png)\n\n### Findings Explorer\n\n![Findings Explorer](screenshots/findings-explorer.png)\n\n### Reports Section\n\n![Reports Section](screenshots/reports-section.png)\n\n### HTML Report\n\n![HTML Report](screenshots/html-report.png)\n\n---\n\n## Security Note\n\nCloudSec Auditor currently supports real AWS read-only scanning through local AWS CLI profiles.\n\nNo AWS access keys, secrets, or credentials are stored in the frontend. Real AWS mode is planned for a future version and should only use read-only AWS permissions through local AWS CLI profiles.\n\nRecommended future permissions for real AWS mode:\n\n* SecurityAudit\n* ViewOnlyAccess\n* Custom least-privilege read-only policy\n\n---\n\n## Current Status\n\nThis project currently includes:\n\n* React dashboard\n* FastAPI backend\n* Real AWS read-only scan engine\n* Risk scoring\n* Findings explorer\n* Report generation\n* Latest report serving\n* API status indicator\n* Helper scripts\n* GitHub-ready project structure\n\n---\n\n## Roadmap\n\nPlanned improvements:\n\n* Real AWS read-only scanning with `boto3`\n* AWS CLI profile selector\n* IAM policy analysis\n* S3 public access analyzer\n* EC2 security group analyzer\n* CloudTrail configuration validation\n* PDF report export\n* Electron desktop packaging\n* CI/CD workflow\n* Release builds\n\n---\n\n## Disclaimer\n\nThis project is built for defensive cloud security auditing, learning, and portfolio demonstration. It should only be used on cloud accounts and environments where proper authorization exists.\n\n\u003c!-- REAL_AWS_MODE_START --\u003e\n## Smoke Test\n\nAfter starting the FastAPI backend, run the safe real AWS smoke test:\n\n    python3 scripts/smoke_test_real_aws.py cloudsec-auditor\n\nThe smoke test verifies:\n\n- Backend health\n- AWS profile discovery\n- AWS profile validation\n- Real AWS read-only scan execution\n- Real AWS report generation\n- Latest report lookup\n\nThe script does not print AWS access keys, secret keys, session tokens, raw account IDs, or full ARNs.\n\n## Sanitized Sample Output\n\nExample sanitized real AWS read-only scan output is available in the `samples/` folder:\n\n- [`sample_aws_readonly_scan_sanitized.json`](samples/sample_aws_readonly_scan_sanitized.json)\n- [`sample_aws_readonly_scan_sanitized.md`](samples/sample_aws_readonly_scan_sanitized.md)\n\nThese samples remove account-specific identity details while preserving the structure of real scan results.\n\n\u003c!-- README_POLISH_START --\u003e\n## Project Status\n\n**CloudSec Auditor** is now a real AWS read-only security posture scanner with a React dashboard, FastAPI backend, boto3-based AWS checks, risk scoring, and exportable JSON, HTML, and Markdown reports.\n\nThe project started as a safe AWS security dashboard and has been upgraded into a real read-only AWS auditing tool for authorized environments.\n\n### Current Capabilities\n\n- Detects local AWS CLI profiles safely\n- Validates AWS profile identity through STS\n- Runs real AWS read-only checks using boto3\n- Audits IAM, S3, EC2 security groups, and CloudTrail\n- Calculates severity counts and overall risk score\n- Generates audit-ready JSON, HTML, and Markdown reports\n- Provides a dark cyber-style React dashboard for viewing findings\n- Includes sanitized sample output and updated screenshots\n\n### Real AWS Services Covered\n\n| Service | Checks |\n|---|---|\n| IAM | Password policy, console MFA, access key age |\n| S3 | Block Public Access, default encryption, versioning |\n| EC2 | Public SSH/RDP exposure across enabled regions |\n| CloudTrail | Trail existence and logging visibility |\n\n### Safety Model\n\n- Read-only AWS API calls only\n- No resource creation, modification, or deletion\n- No AWS access keys, secret keys, or session tokens printed\n- AWS account identity is masked in API responses\n- Intended only for authorized cloud security auditing\n\n### Demo Flow\n\n1. Start the FastAPI backend.\n2. Start the React frontend.\n3. Validate the local AWS CLI profile.\n4. Run AWS read-only scan.\n5. Review prioritized findings.\n6. Export JSON, HTML, or Markdown reports.\n\n\u003c!-- README_POLISH_END --\u003e\n\n## Updated Screenshots\n\n### Real AWS Read-Only Dashboard\n\n![CloudSec Auditor real AWS dashboard](screenshots/v0.2/01_dashboard_aws_scan.png)\n\n### AWS Profile Status\n\n![AWS profile validation card](screenshots/v0.2/02_aws_profile_status.png)\n\n### Findings Explorer\n\n![Findings explorer with real AWS checks](screenshots/v0.2/03_findings_explorer.png)\n\n### Real AWS HTML Report\n\n![AWS HTML report](screenshots/v0.2/04_real_aws_html_report.png)\n\n### Reports Section\n\n![Reports section](screenshots/v0.2/05_reports_section.png)\n\n## Real AWS Read-Only Mode\n\nCloudSec Auditor supports real AWS read-only security scanning through a local AWS CLI profile. The backend validates the selected profile, confirms AWS identity through STS, and runs defensive checks without exposing credential values.\n\n### Implemented Real AWS Checks\n\n| Service | Check | Purpose |\n|---|---|---|\n| IAM | Account password policy | Detects missing IAM password policy controls |\n| IAM | Console user MFA | Detects IAM users with console access but no MFA |\n| IAM | Access key age | Detects active access keys older than 90 days |\n| S3 | Block Public Access | Checks whether buckets block public access |\n| S3 | Default encryption | Checks whether buckets enforce server-side encryption |\n| S3 | Bucket versioning | Checks whether buckets have versioning enabled |\n| EC2 | Public SSH exposure | Detects security groups exposing TCP/22 publicly |\n| EC2 | Public RDP exposure | Detects security groups exposing TCP/3389 publicly |\n| CloudTrail | Trail configured | Detects missing CloudTrail trails |\n| CloudTrail | Logging enabled | Checks whether CloudTrail trails are actively logging |\n\n### Security Model\n\nCloudSec Auditor is designed for defensive and authorized auditing only.\n\n- Uses local AWS CLI profiles\n- Uses read-only AWS API calls\n- Does not print or store AWS access keys\n- Does not expose secret keys or session tokens\n- Does not modify, create, or delete AWS resources\n- Masks sensitive account identity details in API responses\n\nRecommended AWS permissions for testing:\n\n    SecurityAudit\n    ViewOnlyAccess\n\nDo not use root credentials. Do not commit `.aws/`, access keys, screenshots of secrets, or raw AWS credential files.\n\n### AWS Profile Setup\n\nConfigure a local AWS CLI profile:\n\n    aws configure --profile cloudsec-auditor\n\nValidate the configured profile:\n\n    aws sts get-caller-identity --profile cloudsec-auditor\n\n### Backend Endpoints\n\n| Endpoint | Description |\n|---|---|\n| `GET /api/aws/profiles` | Lists local AWS CLI profile names safely |\n| `GET /api/aws/profiles/{profile_name}/validate` | Validates a selected AWS profile through STS |\n| `GET /api/scan/aws/{profile_name}` | Runs real AWS read-only IAM, S3, and EC2 checks |\n\n### Example Real AWS Scan Result\n\nA fresh AWS account may return a result similar to:\n\n    total_checks: 23\n    passed: 22\n    failed: 1\n    critical: 0\n    risk_score: 8\n\nThe most common initial finding is a missing IAM account password policy.\n\n### Current Limitation\n\nReal AWS scanning and report export are implemented for IAM, S3, EC2 security group, and CloudTrail checks.\n\u003c!-- REAL_AWS_MODE_END --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuspecting%2Fcloudsec-auditor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuspecting%2Fcloudsec-auditor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuspecting%2Fcloudsec-auditor/lists"}