clouddetectx 3.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. clouddetectx-3.0.0/LICENSE +21 -0
  2. clouddetectx-3.0.0/PKG-INFO +166 -0
  3. clouddetectx-3.0.0/README.md +124 -0
  4. clouddetectx-3.0.0/clouddetectx/__init__.py +3 -0
  5. clouddetectx-3.0.0/clouddetectx/__main__.py +5 -0
  6. clouddetectx-3.0.0/clouddetectx/account.py +87 -0
  7. clouddetectx-3.0.0/clouddetectx/alerts.py +32 -0
  8. clouddetectx-3.0.0/clouddetectx/analysis.py +132 -0
  9. clouddetectx-3.0.0/clouddetectx/checks/__init__.py +24 -0
  10. clouddetectx-3.0.0/clouddetectx/checks/aws_account.py +281 -0
  11. clouddetectx-3.0.0/clouddetectx/checks/azure_account.py +202 -0
  12. clouddetectx-3.0.0/clouddetectx/checks/gcp_account.py +233 -0
  13. clouddetectx-3.0.0/clouddetectx/checks/rest.py +96 -0
  14. clouddetectx-3.0.0/clouddetectx/cli.py +967 -0
  15. clouddetectx-3.0.0/clouddetectx/compliance.py +269 -0
  16. clouddetectx-3.0.0/clouddetectx/config.py +390 -0
  17. clouddetectx-3.0.0/clouddetectx/config_ui.py +484 -0
  18. clouddetectx-3.0.0/clouddetectx/engine.py +355 -0
  19. clouddetectx-3.0.0/clouddetectx/export.py +176 -0
  20. clouddetectx-3.0.0/clouddetectx/history.py +122 -0
  21. clouddetectx-3.0.0/clouddetectx/iam.py +344 -0
  22. clouddetectx-3.0.0/clouddetectx/interactive.py +659 -0
  23. clouddetectx-3.0.0/clouddetectx/models.py +189 -0
  24. clouddetectx-3.0.0/clouddetectx/overview.py +131 -0
  25. clouddetectx-3.0.0/clouddetectx/probe.py +110 -0
  26. clouddetectx-3.0.0/clouddetectx/prompts.py +52 -0
  27. clouddetectx-3.0.0/clouddetectx/providers/__init__.py +32 -0
  28. clouddetectx-3.0.0/clouddetectx/providers/aws.py +1044 -0
  29. clouddetectx-3.0.0/clouddetectx/providers/azure.py +559 -0
  30. clouddetectx-3.0.0/clouddetectx/providers/base.py +90 -0
  31. clouddetectx-3.0.0/clouddetectx/providers/gcp.py +555 -0
  32. clouddetectx-3.0.0/clouddetectx/reporting.py +383 -0
  33. clouddetectx-3.0.0/clouddetectx/risk.py +71 -0
  34. clouddetectx-3.0.0/clouddetectx/schedule.py +152 -0
  35. clouddetectx-3.0.0/clouddetectx/sensitive.py +442 -0
  36. clouddetectx-3.0.0/clouddetectx/state.py +132 -0
  37. clouddetectx-3.0.0/clouddetectx/waivers.py +123 -0
  38. clouddetectx-3.0.0/clouddetectx/web/__init__.py +1 -0
  39. clouddetectx-3.0.0/clouddetectx/web/server.py +1069 -0
  40. clouddetectx-3.0.0/clouddetectx/web/static/app.js +1578 -0
  41. clouddetectx-3.0.0/clouddetectx/web/static/index.html +37 -0
  42. clouddetectx-3.0.0/clouddetectx/web/static/style.css +497 -0
  43. clouddetectx-3.0.0/clouddetectx.egg-info/PKG-INFO +166 -0
  44. clouddetectx-3.0.0/clouddetectx.egg-info/SOURCES.txt +57 -0
  45. clouddetectx-3.0.0/clouddetectx.egg-info/dependency_links.txt +1 -0
  46. clouddetectx-3.0.0/clouddetectx.egg-info/entry_points.txt +2 -0
  47. clouddetectx-3.0.0/clouddetectx.egg-info/requires.txt +25 -0
  48. clouddetectx-3.0.0/clouddetectx.egg-info/top_level.txt +1 -0
  49. clouddetectx-3.0.0/pyproject.toml +66 -0
  50. clouddetectx-3.0.0/setup.cfg +4 -0
  51. clouddetectx-3.0.0/tests/test_aws_scan.py +79 -0
  52. clouddetectx-3.0.0/tests/test_azure_gcp_checks.py +104 -0
  53. clouddetectx-3.0.0/tests/test_cli.py +69 -0
  54. clouddetectx-3.0.0/tests/test_discovery.py +100 -0
  55. clouddetectx-3.0.0/tests/test_export_schedule_config.py +124 -0
  56. clouddetectx-3.0.0/tests/test_iam.py +44 -0
  57. clouddetectx-3.0.0/tests/test_tui.py +70 -0
  58. clouddetectx-3.0.0/tests/test_waivers_state_rollback.py +142 -0
  59. clouddetectx-3.0.0/tests/test_web.py +145 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dipanshwave
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,166 @@
1
+ Metadata-Version: 2.4
2
+ Name: clouddetectx
3
+ Version: 3.0.0
4
+ Summary: Find exposed cloud storage, prove what's reachable and inside, investigate access, and fix it - AWS, Azure and GCP.
5
+ Author: dipanshwave
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/dipanshwave/CloudDetectX-exposure-detector
8
+ Keywords: security,cloud,s3,azure,gcp,cspm,compliance,incident-response
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Topic :: Security
12
+ Classifier: Environment :: Console
13
+ Classifier: Environment :: Web Environment
14
+ Requires-Python: >=3.10
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Requires-Dist: rich<16,>=13
18
+ Requires-Dist: questionary<3,>=2
19
+ Requires-Dist: python-dotenv<2,>=1
20
+ Requires-Dist: keyring<26,>=24
21
+ Requires-Dist: requests<3,>=2.31
22
+ Requires-Dist: fastapi>=0.110
23
+ Requires-Dist: uvicorn>=0.27
24
+ Requires-Dist: markdown<4,>=3.5
25
+ Requires-Dist: nh3<1,>=0.2
26
+ Requires-Dist: fpdf2<3,>=2.7
27
+ Requires-Dist: pypdf<8,>=4
28
+ Requires-Dist: pyarrow>=14
29
+ Requires-Dist: boto3<2,>=1.34
30
+ Requires-Dist: azure-identity<2,>=1.15
31
+ Requires-Dist: azure-mgmt-storage>=21
32
+ Requires-Dist: azure-mgmt-monitor>=6
33
+ Requires-Dist: azure-monitor-query>=1.2
34
+ Requires-Dist: azure-storage-blob<13,>=12.19
35
+ Requires-Dist: google-cloud-storage<4,>=2.14
36
+ Requires-Dist: google-cloud-logging<4,>=3.9
37
+ Provides-Extra: dev
38
+ Requires-Dist: pytest>=8; extra == "dev"
39
+ Requires-Dist: moto[all]<6,>=5; extra == "dev"
40
+ Requires-Dist: httpx>=0.27; extra == "dev"
41
+ Dynamic: license-file
42
+
43
+ # 🛡️ CloudDetectX
44
+
45
+ > **Find it. Prove it. Seal it.** Find exposed cloud storage and risky account settings, prove what's reachable and what's inside, see who got in, and fix it, with a report at the end.
46
+
47
+ CloudDetectX checks **AWS, Azure and Google Cloud** for misconfigurations using your existing cloud logins. It runs as a local **web dashboard**, an **interactive terminal UI**, or **scriptable commands**.
48
+
49
+ <picture>
50
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/dashboard-dark.png">
51
+ <img alt="CloudDetectX dashboard: security score gauge with grade, publicly exposed count, eight security-posture tiles, a fix-these-first list and compliance pass rates" src="https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/dashboard.png">
52
+ </picture>
53
+
54
+ <sub>Screenshots use a simulated AWS account with fake data.</sub>
55
+
56
+ ## What it does
57
+
58
+ - **Storage exposure**: public ACLs, policies, containers and access points; missing Block Public Access / Public Access Prevention; buckets shared with other accounts; CloudFront without origin access control.
59
+ - **Account-wide checks**: audit logging (CloudTrail, Activity Log, Data Access logs), root MFA and keys, password policy, firewalls open to the internet, public databases and snapshots, Kubernetes endpoints, KMS rotation, EBS default encryption.
60
+ - **IAM**: AWS users/roles/groups, Azure RBAC and GCP IAM. Finds admins, full-storage access, who can make buckets public, missing MFA and old keys, and who can access each bucket.
61
+ - **Proof and content**: anonymous requests prove what's reachable; data discovery finds secrets and personal data in text, PDF, Word/Excel/PowerPoint, zip/tar/gzip and Parquet files. Every match is redacted.
62
+ - **Investigation**: who downloaded what and from where, and who made it public, tagged with MITRE ATT&CK.
63
+ - **Scores and compliance**: risk per resource, a graded security score, and pass rates for NIST 800-53, CIS Controls v8, ISO 27001 and the CIS cloud benchmarks.
64
+ - **Fix and undo**: removes public access only, keeps other permissions, and can **roll back** from the saved configuration.
65
+ - **Accept risks**: mark intended exposure (e.g. a website bucket) with a reason and expiry date. It stops counting until it expires.
66
+ - **Scale**: parallel scanning and **all accounts** at once (AWS Organizations, every Azure subscription, every GCP project).
67
+ - **Reports and monitoring**: incident and compliance reports (Markdown, JSON, PDF), SARIF / OCSF / CSV exports, scan history and drift, webhook alerts, and **scheduled scans** (Task Scheduler / cron).
68
+
69
+ ## Quick start
70
+
71
+ ```bash
72
+ git clone https://github.com/dipanshwave/CloudDetectX-exposure-detector
73
+ cd CloudDetectX-exposure-detector
74
+ python -m venv .venv
75
+ .venv\Scripts\activate # Linux/macOS: source .venv/bin/activate
76
+ pip install -r requirements.txt # or: pip install . (adds a `clouddetectx` command)
77
+ python main.py web # dashboard; the first visit opens the setup wizard
78
+ ```
79
+
80
+ Everything is configured in the app: the setup wizard, **Settings** (web or terminal), or `python main.py config`. Settings go to `.env` (git-ignored). Secrets such as the webhook URL go to your **OS keychain** when one is available. When installed with pip, settings live in `%APPDATA%\clouddetectx` (Windows) or `~/.config/clouddetectx`.
81
+
82
+ ## Usage
83
+
84
+ ```bash
85
+ python main.py web # web dashboard at http://127.0.0.1:8765
86
+ python main.py # interactive terminal menus
87
+
88
+ python main.py -p aws,azure,gcp scan # scan + account checks + drift + alerts
89
+ python main.py -p aws scan --all-accounts # every Organizations account / subscription / project
90
+ python main.py -p aws account # IAM and account-wide findings
91
+ python main.py -p aws verify my-bucket # test from the internet, no credentials
92
+ python main.py -p aws discover my-bucket # find secrets / personal data (redacted)
93
+ python main.py -p aws investigate my-bucket --days 90
94
+ python main.py -p aws remediate my-bucket --dry-run
95
+ python main.py rollback INC-20261118-054001-aws-my-bucket
96
+ python main.py -p aws waivers add my-website --check '*' --reason "public website" --expires 2027-06-30
97
+ python main.py -p aws compliance --report --pdf
98
+ python main.py -p aws export --format sarif -o findings.sarif # also: ocsf, csv, all
99
+ python main.py -p aws schedule install --every 1440 # daily scan via Task Scheduler / cron
100
+ ```
101
+
102
+ Exit codes: `0` nothing exposed, `2` exposure found, `1` error. Run `python main.py <command> --help` for options.
103
+
104
+ ## Screenshots
105
+
106
+ | Account & IAM | Access & encryption |
107
+ |---|---|
108
+ | ![Account and IAM page: account-wide findings such as root without MFA and public snapshots, with control mappings and accept-risk buttons](https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/identity-access.png) | ![Bucket access tab: encryption status and which users and roles can read, write or change access](https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/access-encryption.png) |
109
+ | **Accepted risk** | **Rollback** |
110
+ | ![A public website bucket with all findings accepted by a waiver, showing reason and expiry](https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/accepted-risk.png) | ![Incident report with PDF download and a Roll back button](https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/rollback.png) |
111
+ | **Data discovery** | **Compliance** |
112
+ | ![Data discovery: secrets and personal data found, shown only as redacted samples](https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/data-discovery.png) | ![Compliance: pass rate per framework and failing controls with affected resources](https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/compliance.png) |
113
+
114
+ More are in [docs/screenshots](https://github.com/dipanshwave/CloudDetectX-exposure-detector/tree/main/docs/screenshots): setup wizard, investigation, exposure test, remediation, history, settings and [CLI output](https://github.com/dipanshwave/CloudDetectX-exposure-detector/blob/main/docs/screenshots/cli-scan.svg).
115
+
116
+ ## Safety
117
+
118
+ - **Read-only by default.** Only remediation and rollback change anything. Both show the plan first and need you to type the resource name (or `-y` in scripts).
119
+ - **Minimal, reversible changes.** Only public access is removed (plus optional `--harden`). The previous configuration is saved in the report, and `rollback` restores it.
120
+ - **Secrets stay redacted** in reports, history, exports and the dashboard. Credentials go to the OS keychain.
121
+ - **The dashboard is local only**: it listens on `127.0.0.1` and is opened with a one-time link.
122
+
123
+ ## Permissions
124
+
125
+ | | Read-only (scan, account, investigate) | Discovery | Remediation and rollback |
126
+ |---|---|---|---|
127
+ | **AWS** | `SecurityAudit` + `s3:GetObject` on log buckets | `s3:ListBucket`, `s3:GetObject` | `s3:PutBucketPublicAccessBlock`, `PutBucketAcl`, `PutBucketPolicy`, `DeleteBucketPolicy`, `PutObjectAcl` |
128
+ | **Azure** | `Reader`, `Monitoring Reader`, `Log Analytics Reader` | `Storage Blob Data Reader` | `Storage Account Contributor` |
129
+ | **GCP** | `roles/iam.securityReviewer`, `roles/logging.privateLogViewer`, `roles/cloudsql.viewer`, `roles/compute.viewer`, `roles/container.viewer` | `roles/storage.objectViewer` | `storage.buckets.update`, `storage.buckets.setIamPolicy`, `storage.objects.setIamPolicy` |
130
+
131
+ **All accounts**: AWS needs `organizations:ListAccounts` in the management (or delegated admin) account, plus a read-only role in each member account (set its name under *Settings > AWS*). Azure and GCP use every subscription/project your login can read.
132
+
133
+ **First real run:** start with `python main.py whoami`, then a read-only `scan`. If a check lacks permission it is skipped and listed, never fatal. Limit account checks to the regions you use under *Settings > AWS > Regions for account checks* for faster scans.
134
+
135
+ ## Limits
136
+
137
+ - Not a full CSPM: storage, IAM and the account-wide checks above are covered. Compute instance settings, serverless code, container images and IaC aren't.
138
+ - IAM analysis reads policies directly. It doesn't evaluate SCPs, permission boundaries or condition values (marked "conditional"). Azure principals are shown by object ID.
139
+ - Compliance mapping is audit evidence, not a certification.
140
+ - Discovery can't read images, 7z/rar archives or encrypted PDFs. Reading objects can incur request/egress charges.
141
+
142
+ ## Development
143
+
144
+ ```bash
145
+ pip install -r requirements.txt -r requirements-dev.txt
146
+ python -m pytest # 45 tests; AWS is simulated with moto, nothing touches real clouds
147
+ ```
148
+
149
+ CI runs the suite on Linux and Windows ([.github/workflows/tests.yml](https://github.com/dipanshwave/CloudDetectX-exposure-detector/blob/main/.github/workflows/tests.yml)).
150
+
151
+ ```text
152
+ clouddetectx/
153
+ ├── providers/ aws.py, azure.py, gcp.py (storage checks, remediation, rollback)
154
+ ├── checks/ account-wide checks and Azure/GCP IAM
155
+ ├── web/ local dashboard (FastAPI + plain JS)
156
+ ├── cli.py commands interactive.py terminal UI
157
+ ├── engine.py scan workflow waivers.py accepted risks
158
+ ├── iam.py AWS IAM analysis sensitive.py data discovery
159
+ ├── compliance.py control maps reporting.py reports
160
+ ├── export.py SARIF/OCSF/CSV/PDF schedule.py scheduled scans
161
+ └── ... state, history, risk, alerts, probe, analysis
162
+ ```
163
+
164
+ ---
165
+
166
+ MIT licensed. For **authorised use only**: scan only accounts you own or have permission to assess.
@@ -0,0 +1,124 @@
1
+ # 🛡️ CloudDetectX
2
+
3
+ > **Find it. Prove it. Seal it.** Find exposed cloud storage and risky account settings, prove what's reachable and what's inside, see who got in, and fix it, with a report at the end.
4
+
5
+ CloudDetectX checks **AWS, Azure and Google Cloud** for misconfigurations using your existing cloud logins. It runs as a local **web dashboard**, an **interactive terminal UI**, or **scriptable commands**.
6
+
7
+ <picture>
8
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/dashboard-dark.png">
9
+ <img alt="CloudDetectX dashboard: security score gauge with grade, publicly exposed count, eight security-posture tiles, a fix-these-first list and compliance pass rates" src="https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/dashboard.png">
10
+ </picture>
11
+
12
+ <sub>Screenshots use a simulated AWS account with fake data.</sub>
13
+
14
+ ## What it does
15
+
16
+ - **Storage exposure**: public ACLs, policies, containers and access points; missing Block Public Access / Public Access Prevention; buckets shared with other accounts; CloudFront without origin access control.
17
+ - **Account-wide checks**: audit logging (CloudTrail, Activity Log, Data Access logs), root MFA and keys, password policy, firewalls open to the internet, public databases and snapshots, Kubernetes endpoints, KMS rotation, EBS default encryption.
18
+ - **IAM**: AWS users/roles/groups, Azure RBAC and GCP IAM. Finds admins, full-storage access, who can make buckets public, missing MFA and old keys, and who can access each bucket.
19
+ - **Proof and content**: anonymous requests prove what's reachable; data discovery finds secrets and personal data in text, PDF, Word/Excel/PowerPoint, zip/tar/gzip and Parquet files. Every match is redacted.
20
+ - **Investigation**: who downloaded what and from where, and who made it public, tagged with MITRE ATT&CK.
21
+ - **Scores and compliance**: risk per resource, a graded security score, and pass rates for NIST 800-53, CIS Controls v8, ISO 27001 and the CIS cloud benchmarks.
22
+ - **Fix and undo**: removes public access only, keeps other permissions, and can **roll back** from the saved configuration.
23
+ - **Accept risks**: mark intended exposure (e.g. a website bucket) with a reason and expiry date. It stops counting until it expires.
24
+ - **Scale**: parallel scanning and **all accounts** at once (AWS Organizations, every Azure subscription, every GCP project).
25
+ - **Reports and monitoring**: incident and compliance reports (Markdown, JSON, PDF), SARIF / OCSF / CSV exports, scan history and drift, webhook alerts, and **scheduled scans** (Task Scheduler / cron).
26
+
27
+ ## Quick start
28
+
29
+ ```bash
30
+ git clone https://github.com/dipanshwave/CloudDetectX-exposure-detector
31
+ cd CloudDetectX-exposure-detector
32
+ python -m venv .venv
33
+ .venv\Scripts\activate # Linux/macOS: source .venv/bin/activate
34
+ pip install -r requirements.txt # or: pip install . (adds a `clouddetectx` command)
35
+ python main.py web # dashboard; the first visit opens the setup wizard
36
+ ```
37
+
38
+ Everything is configured in the app: the setup wizard, **Settings** (web or terminal), or `python main.py config`. Settings go to `.env` (git-ignored). Secrets such as the webhook URL go to your **OS keychain** when one is available. When installed with pip, settings live in `%APPDATA%\clouddetectx` (Windows) or `~/.config/clouddetectx`.
39
+
40
+ ## Usage
41
+
42
+ ```bash
43
+ python main.py web # web dashboard at http://127.0.0.1:8765
44
+ python main.py # interactive terminal menus
45
+
46
+ python main.py -p aws,azure,gcp scan # scan + account checks + drift + alerts
47
+ python main.py -p aws scan --all-accounts # every Organizations account / subscription / project
48
+ python main.py -p aws account # IAM and account-wide findings
49
+ python main.py -p aws verify my-bucket # test from the internet, no credentials
50
+ python main.py -p aws discover my-bucket # find secrets / personal data (redacted)
51
+ python main.py -p aws investigate my-bucket --days 90
52
+ python main.py -p aws remediate my-bucket --dry-run
53
+ python main.py rollback INC-20261118-054001-aws-my-bucket
54
+ python main.py -p aws waivers add my-website --check '*' --reason "public website" --expires 2027-06-30
55
+ python main.py -p aws compliance --report --pdf
56
+ python main.py -p aws export --format sarif -o findings.sarif # also: ocsf, csv, all
57
+ python main.py -p aws schedule install --every 1440 # daily scan via Task Scheduler / cron
58
+ ```
59
+
60
+ Exit codes: `0` nothing exposed, `2` exposure found, `1` error. Run `python main.py <command> --help` for options.
61
+
62
+ ## Screenshots
63
+
64
+ | Account & IAM | Access & encryption |
65
+ |---|---|
66
+ | ![Account and IAM page: account-wide findings such as root without MFA and public snapshots, with control mappings and accept-risk buttons](https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/identity-access.png) | ![Bucket access tab: encryption status and which users and roles can read, write or change access](https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/access-encryption.png) |
67
+ | **Accepted risk** | **Rollback** |
68
+ | ![A public website bucket with all findings accepted by a waiver, showing reason and expiry](https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/accepted-risk.png) | ![Incident report with PDF download and a Roll back button](https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/rollback.png) |
69
+ | **Data discovery** | **Compliance** |
70
+ | ![Data discovery: secrets and personal data found, shown only as redacted samples](https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/data-discovery.png) | ![Compliance: pass rate per framework and failing controls with affected resources](https://raw.githubusercontent.com/dipanshwave/CloudDetectX-exposure-detector/main/docs/screenshots/compliance.png) |
71
+
72
+ More are in [docs/screenshots](https://github.com/dipanshwave/CloudDetectX-exposure-detector/tree/main/docs/screenshots): setup wizard, investigation, exposure test, remediation, history, settings and [CLI output](https://github.com/dipanshwave/CloudDetectX-exposure-detector/blob/main/docs/screenshots/cli-scan.svg).
73
+
74
+ ## Safety
75
+
76
+ - **Read-only by default.** Only remediation and rollback change anything. Both show the plan first and need you to type the resource name (or `-y` in scripts).
77
+ - **Minimal, reversible changes.** Only public access is removed (plus optional `--harden`). The previous configuration is saved in the report, and `rollback` restores it.
78
+ - **Secrets stay redacted** in reports, history, exports and the dashboard. Credentials go to the OS keychain.
79
+ - **The dashboard is local only**: it listens on `127.0.0.1` and is opened with a one-time link.
80
+
81
+ ## Permissions
82
+
83
+ | | Read-only (scan, account, investigate) | Discovery | Remediation and rollback |
84
+ |---|---|---|---|
85
+ | **AWS** | `SecurityAudit` + `s3:GetObject` on log buckets | `s3:ListBucket`, `s3:GetObject` | `s3:PutBucketPublicAccessBlock`, `PutBucketAcl`, `PutBucketPolicy`, `DeleteBucketPolicy`, `PutObjectAcl` |
86
+ | **Azure** | `Reader`, `Monitoring Reader`, `Log Analytics Reader` | `Storage Blob Data Reader` | `Storage Account Contributor` |
87
+ | **GCP** | `roles/iam.securityReviewer`, `roles/logging.privateLogViewer`, `roles/cloudsql.viewer`, `roles/compute.viewer`, `roles/container.viewer` | `roles/storage.objectViewer` | `storage.buckets.update`, `storage.buckets.setIamPolicy`, `storage.objects.setIamPolicy` |
88
+
89
+ **All accounts**: AWS needs `organizations:ListAccounts` in the management (or delegated admin) account, plus a read-only role in each member account (set its name under *Settings > AWS*). Azure and GCP use every subscription/project your login can read.
90
+
91
+ **First real run:** start with `python main.py whoami`, then a read-only `scan`. If a check lacks permission it is skipped and listed, never fatal. Limit account checks to the regions you use under *Settings > AWS > Regions for account checks* for faster scans.
92
+
93
+ ## Limits
94
+
95
+ - Not a full CSPM: storage, IAM and the account-wide checks above are covered. Compute instance settings, serverless code, container images and IaC aren't.
96
+ - IAM analysis reads policies directly. It doesn't evaluate SCPs, permission boundaries or condition values (marked "conditional"). Azure principals are shown by object ID.
97
+ - Compliance mapping is audit evidence, not a certification.
98
+ - Discovery can't read images, 7z/rar archives or encrypted PDFs. Reading objects can incur request/egress charges.
99
+
100
+ ## Development
101
+
102
+ ```bash
103
+ pip install -r requirements.txt -r requirements-dev.txt
104
+ python -m pytest # 45 tests; AWS is simulated with moto, nothing touches real clouds
105
+ ```
106
+
107
+ CI runs the suite on Linux and Windows ([.github/workflows/tests.yml](https://github.com/dipanshwave/CloudDetectX-exposure-detector/blob/main/.github/workflows/tests.yml)).
108
+
109
+ ```text
110
+ clouddetectx/
111
+ ├── providers/ aws.py, azure.py, gcp.py (storage checks, remediation, rollback)
112
+ ├── checks/ account-wide checks and Azure/GCP IAM
113
+ ├── web/ local dashboard (FastAPI + plain JS)
114
+ ├── cli.py commands interactive.py terminal UI
115
+ ├── engine.py scan workflow waivers.py accepted risks
116
+ ├── iam.py AWS IAM analysis sensitive.py data discovery
117
+ ├── compliance.py control maps reporting.py reports
118
+ ├── export.py SARIF/OCSF/CSV/PDF schedule.py scheduled scans
119
+ └── ... state, history, risk, alerts, probe, analysis
120
+ ```
121
+
122
+ ---
123
+
124
+ MIT licensed. For **authorised use only**: scan only accounts you own or have permission to assess.
@@ -0,0 +1,3 @@
1
+ """CloudDetectX: detect, investigate and remediate public cloud storage."""
2
+
3
+ __version__ = "3.0.0"
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from clouddetectx.cli import main
4
+
5
+ sys.exit(main())
@@ -0,0 +1,87 @@
1
+ """Account-level review: IAM principals plus account-wide findings (audit logging, root/owner
2
+ security, network exposure, public databases and snapshots, key rotation).
3
+
4
+ One AccountReview per scanned account (AWS account, Azure subscription, GCP project).
5
+ Several reviews (all-accounts scans) are merged with merge_reviews().
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from dataclasses import dataclass, field
11
+ from datetime import datetime, timezone
12
+
13
+ from clouddetectx.models import Finding
14
+
15
+ ACCOUNT_PREFIX = "account:" # waiver resource for account-level findings: "account:<account id>"
16
+
17
+
18
+ def account_resource(account_id: str | None) -> str:
19
+ return f"{ACCOUNT_PREFIX}{account_id or 'default'}"
20
+
21
+
22
+ @dataclass
23
+ class AccountReview:
24
+ provider: str
25
+ account_id: str
26
+ iam: object | None = None # iam.IamReport
27
+ findings: list[Finding] = field(default_factory=list) # active (not waived), incl. IAM findings
28
+ waived: list[Finding] = field(default_factory=list)
29
+ notes: list[str] = field(default_factory=list)
30
+ errors: dict[str, str] = field(default_factory=dict) # check area -> error (e.g. missing permission)
31
+ analyzed_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
32
+
33
+ @property
34
+ def waiver_resource(self) -> str:
35
+ return account_resource(self.account_id)
36
+
37
+ def counts(self) -> dict:
38
+ c = self.iam.counts() if self.iam is not None else {}
39
+ return {**c, "findings": len(self.findings), "waived": len(self.waived)}
40
+
41
+ def to_dict(self) -> dict:
42
+ return {
43
+ "provider": self.provider, "account_id": self.account_id,
44
+ "analyzed_at": self.analyzed_at.isoformat(),
45
+ "waiver_resource": self.waiver_resource,
46
+ "iam": self.iam.to_dict() if self.iam is not None else None,
47
+ "findings": [f.to_dict() for f in self.findings],
48
+ "waived": [f.to_dict() for f in self.waived],
49
+ "notes": self.notes, "errors": self.errors,
50
+ }
51
+
52
+
53
+ def merge_reviews(reviews: list[AccountReview]) -> AccountReview | None:
54
+ """Combine per-account reviews (all-accounts scans) into one view."""
55
+ reviews = [r for r in reviews if r is not None]
56
+ if not reviews:
57
+ return None
58
+ if len(reviews) == 1:
59
+ return reviews[0]
60
+ from clouddetectx.iam import IamReport
61
+
62
+ def tag(f: Finding, acct: str) -> Finding:
63
+ f.evidence = {**(f.evidence or {}), "account": acct}
64
+ return f
65
+
66
+ principals, iam_notes, skipped = [], [], 0
67
+ for r in reviews:
68
+ if r.iam is not None:
69
+ for p in r.iam.principals:
70
+ if not p.name.startswith(f"{r.account_id}/"):
71
+ p.name = f"{r.account_id}/{p.name}"
72
+ principals.append(p)
73
+ skipped += r.iam.skipped_service_roles
74
+ iam_notes += [n for n in r.iam.notes if n not in iam_notes]
75
+ merged_iam = None
76
+ if any(r.iam is not None for r in reviews):
77
+ merged_iam = IamReport("multiple", principals,
78
+ [f for r in reviews if r.iam is not None for f in r.iam.findings], iam_notes, skipped)
79
+ return AccountReview(
80
+ provider=reviews[0].provider,
81
+ account_id="all",
82
+ iam=merged_iam,
83
+ findings=[tag(f, r.account_id) for r in reviews for f in r.findings],
84
+ waived=[tag(f, r.account_id) for r in reviews for f in r.waived],
85
+ notes=[f"{r.account_id}: {n}" for r in reviews for n in r.notes],
86
+ errors={f"{r.account_id}: {k}": v for r in reviews for k, v in r.errors.items()},
87
+ )
@@ -0,0 +1,32 @@
1
+ """Webhook alerts (Slack, Microsoft Teams incoming webhooks, or any endpoint accepting JSON).
2
+
3
+ The payload carries a plain `text` field (rendered by Slack and Teams) plus a structured
4
+ `clouddetectx` object for SIEMs and automation.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ import urllib.error
11
+ import urllib.request
12
+
13
+ from clouddetectx import __version__
14
+
15
+
16
+ class AlertError(RuntimeError):
17
+ pass
18
+
19
+
20
+ def send(webhook_url: str, title: str, lines: list[str], data: dict | None = None, timeout: float = 10.0) -> None:
21
+ text = f"*{title}*\n" + "\n".join(f"• {line}" for line in lines)
22
+ body = json.dumps({"text": text, "clouddetectx": {"title": title, "details": lines, **(data or {})}}).encode()
23
+ req = urllib.request.Request(webhook_url, data=body, method="POST",
24
+ headers={"Content-Type": "application/json", "User-Agent": f"CloudDetectX/{__version__}"})
25
+ try:
26
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
27
+ if resp.status >= 300:
28
+ raise AlertError(f"Webhook returned HTTP {resp.status}")
29
+ except urllib.error.HTTPError as exc:
30
+ raise AlertError(f"Webhook returned HTTP {exc.code}: {exc.reason}") from exc
31
+ except (urllib.error.URLError, TimeoutError, OSError) as exc:
32
+ raise AlertError(f"Webhook request failed: {getattr(exc, 'reason', exc)}") from exc
@@ -0,0 +1,132 @@
1
+ """Provider-neutral analysis of access logs: did anyone outside actually get the data?"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import ipaddress
6
+ from collections import Counter, defaultdict
7
+
8
+ from clouddetectx.models import AccessEvent, ChangeEvent, Indicator, Investigation, Severity
9
+
10
+ DOWNLOAD_OPS = {"GetObject"}
11
+ LIST_OPS = {"ListBucket"}
12
+ WRITE_OPS = {"PutObject", "DeleteObject", "PutObjectAcl"}
13
+
14
+ BULK_OBJECTS_PER_IP = 10
15
+ BULK_REQUESTS_PER_IP = 100
16
+ PROBING_DENIED_THRESHOLD = 5
17
+ TOOLING_AGENTS = ("curl", "wget", "python-requests", "python-urllib", "go-http-client", "aiohttp", "masscan",
18
+ "zgrab", "nuclei", "sqlmap", "nmap", "scrapy", "httpx", "bucket", "s3scanner", "grayhatwarfare")
19
+
20
+ VERDICT_TEXT = {
21
+ "DATA_ACCESSED": "Untrusted parties successfully read or modified data while it was exposed.",
22
+ "EXPOSURE_PROBED": "Untrusted parties reached the resource but no successful data read was recorded.",
23
+ "NO_EVIDENCE_OF_ACCESS": "Logs were available and show no access from untrusted parties.",
24
+ "NO_LOGS_AVAILABLE": "No access logs are available; it cannot be ruled out that data was accessed.",
25
+ }
26
+
27
+
28
+ def is_external(ip: str | None, trusted: list) -> bool:
29
+ if not ip:
30
+ return False
31
+ try:
32
+ addr = ipaddress.ip_address(ip.strip("[]"))
33
+ except ValueError:
34
+ return False # e.g. "AWS Internal" or a service hostname
35
+ if any(addr in net for net in trusted):
36
+ return False
37
+ return addr.is_global
38
+
39
+
40
+ def analyze_access(
41
+ events: list[AccessEvent],
42
+ changes: list[ChangeEvent],
43
+ sources: list[str],
44
+ notes: list[str],
45
+ trusted_networks: list,
46
+ ) -> Investigation:
47
+ def untrusted(e: AccessEvent) -> bool:
48
+ return e.anonymous or is_external(e.source_ip, trusted_networks)
49
+
50
+ suspect = [e for e in events if untrusted(e)]
51
+ downloads = [e for e in suspect if e.operation in DOWNLOAD_OPS and e.succeeded]
52
+ listings = [e for e in suspect if e.operation in LIST_OPS and e.succeeded]
53
+ writes = [e for e in suspect if e.operation in WRITE_OPS and e.succeeded]
54
+ denied = [e for e in suspect if e.status in (401, 403)]
55
+
56
+ per_ip_requests = Counter(e.source_ip or "unknown" for e in suspect)
57
+ per_ip_objects: dict[str, set] = defaultdict(set)
58
+ for e in downloads:
59
+ per_ip_objects[e.source_ip or "unknown"].add(e.key)
60
+
61
+ summary = {
62
+ "total_events": len(events),
63
+ "first_event": events[0].timestamp.isoformat() if events else None,
64
+ "last_event": events[-1].timestamp.isoformat() if events else None,
65
+ "unique_source_ips": len({e.source_ip for e in events if e.source_ip}),
66
+ "untrusted_requests": len(suspect),
67
+ "anonymous_requests": sum(1 for e in events if e.anonymous),
68
+ "external_ips": sorted({e.source_ip for e in suspect if e.source_ip}),
69
+ "objects_downloaded_by_untrusted": sorted({e.key for e in downloads if e.key}),
70
+ "bytes_downloaded_by_untrusted": sum(e.bytes_sent for e in downloads),
71
+ "successful_listings_by_untrusted": len(listings),
72
+ "writes_by_untrusted": len(writes),
73
+ "denied_requests_from_untrusted": len(denied),
74
+ "top_untrusted_ips": per_ip_requests.most_common(10),
75
+ }
76
+
77
+ indicators: list[Indicator] = []
78
+ if downloads:
79
+ indicators.append(Indicator(
80
+ Severity.CRITICAL, "Data downloaded by untrusted parties",
81
+ f"{len(summary['objects_downloaded_by_untrusted'])} object(s), {summary['bytes_downloaded_by_untrusted']:,} bytes, "
82
+ f"from {len({e.source_ip for e in downloads})} source IP(s).", "T1530",
83
+ ))
84
+ deletes = [e for e in writes if e.operation == "DeleteObject"]
85
+ if writes:
86
+ indicators.append(Indicator(
87
+ Severity.CRITICAL, "Data modified by untrusted parties",
88
+ f"{len(writes)} successful write/delete request(s): "
89
+ + ", ".join(sorted({f'{e.operation} {e.key}' for e in writes})[:10]),
90
+ "T1485" if deletes and len(deletes) == len(writes) else "T1565.001",
91
+ ))
92
+ if listings:
93
+ indicators.append(Indicator(Severity.HIGH, "Bucket contents enumerated",
94
+ f"{len(listings)} successful anonymous/external listing request(s).", "T1619"))
95
+ for ip, objs in per_ip_objects.items():
96
+ if len(objs) >= BULK_OBJECTS_PER_IP:
97
+ indicators.append(Indicator(Severity.HIGH, f"Bulk download from {ip}", f"{len(objs)} distinct objects downloaded.", "T1530"))
98
+ for ip, count in per_ip_requests.items():
99
+ if count >= BULK_REQUESTS_PER_IP and len(per_ip_objects.get(ip, ())) < BULK_OBJECTS_PER_IP:
100
+ indicators.append(Indicator(Severity.MEDIUM, f"High request volume from {ip}", f"{count} requests."))
101
+ if len(denied) >= PROBING_DENIED_THRESHOLD:
102
+ indicators.append(Indicator(Severity.MEDIUM, "Access-denied probing",
103
+ f"{len(denied)} denied requests from untrusted sources.", "T1595"))
104
+ tools = sorted({e.user_agent for e in suspect if e.user_agent and any(t in e.user_agent.lower() for t in TOOLING_AGENTS)})
105
+ if tools:
106
+ indicators.append(Indicator(Severity.MEDIUM, "Automated tooling observed", "; ".join(t[:80] for t in tools[:5])))
107
+ for c in changes:
108
+ indicators.append(Indicator(Severity.INFO, f"Configuration change: {c.action}",
109
+ f"{c.timestamp:%Y-%m-%d %H:%M:%S} UTC by {c.actor or 'unknown'} from {c.source_ip or 'unknown IP'}"))
110
+
111
+ if not sources:
112
+ verdict = "NO_LOGS_AVAILABLE"
113
+ elif downloads or writes:
114
+ verdict = "DATA_ACCESSED"
115
+ elif suspect:
116
+ verdict = "EXPOSURE_PROBED"
117
+ else:
118
+ verdict = "NO_EVIDENCE_OF_ACCESS"
119
+
120
+ # Keep reports bounded: every untrusted event plus a sample of the rest.
121
+ kept = suspect + [e for e in events if not untrusted(e)][: max(0, 2000 - len(suspect))]
122
+ kept.sort(key=lambda e: e.timestamp)
123
+
124
+ return Investigation(
125
+ verdict=verdict,
126
+ summary=summary,
127
+ indicators=indicators,
128
+ access_events=kept,
129
+ change_events=changes,
130
+ log_sources=sources,
131
+ notes=notes,
132
+ )
@@ -0,0 +1,24 @@
1
+ """Account-wide checks (beyond individual buckets) and Azure/GCP identity analysis."""
2
+
3
+ # Ports that should never be open to the whole internet.
4
+ EXPOSED_PORTS = {
5
+ 22: "SSH", 23: "Telnet", 445: "SMB", 1433: "SQL Server", 1521: "Oracle", 2375: "Docker API",
6
+ 3306: "MySQL", 3389: "RDP", 5432: "PostgreSQL", 5601: "Kibana", 6379: "Redis", 9200: "Elasticsearch",
7
+ 11211: "Memcached", 27017: "MongoDB",
8
+ }
9
+ OPEN_CIDRS = {"0.0.0.0/0", "::/0", "*", "Internet", "Any", "0.0.0.0"}
10
+
11
+
12
+ def risky_ports(from_port, to_port, all_traffic: bool = False) -> list[str]:
13
+ """Names of sensitive ports inside [from_port, to_port]."""
14
+ if all_traffic or from_port in (None, -1):
15
+ return ["all ports"]
16
+ lo, hi = int(from_port), int(to_port if to_port not in (None, -1) else from_port)
17
+ if lo == 0 and hi >= 65535:
18
+ return ["all ports"]
19
+ return [f"{p} ({name})" for p, name in sorted(EXPOSED_PORTS.items()) if lo <= p <= hi]
20
+
21
+
22
+ def short_list(items: list, limit: int = 8) -> str:
23
+ items = [str(i) for i in items]
24
+ return ", ".join(items[:limit]) + (f" and {len(items) - limit} more" if len(items) > limit else "")