rimscan-cli 1.0.0__tar.gz

rimscan_cli-1.0.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Rimscan
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

rimscan_cli-1.0.0/NOTICE

@@ -0,0 +1,8 @@
+rimscan-cli
+Copyright 2026 Rimscan. Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+Third-party data
+----------------
+rimscan_cli/data/fingerprints.json is derived from the can-i-take-over-xyz project
+(https://github.com/EdOverflow/can-i-take-over-xyz). The fingerprints remain subject to
+that project's license and terms. Review them before redistributing the data file.

rimscan_cli-1.0.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: rimscan-cli
+Version: 1.0.0
+Summary: External attack-surface reconnaissance for domains you own or are authorized to test.
+Author: Rimscan
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://rimscan.cloud
+Project-URL: Repository, https://github.com/Revenge8/Rimscan-cli
+Project-URL: Issues, https://github.com/Revenge8/Rimscan-cli/issues
+Keywords: security,reconnaissance,attack-surface,subdomain-takeover,dns
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: certifi>=2023.7.22
+Requires-Dist: dnspython>=2.4
+Requires-Dist: requests>=2.31
+Requires-Dist: urllib3>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+![RimScan](Rimscan.png)
+
+# Rimscan CLI
+
+![tests](https://github.com/Revenge8/Rimscan-cli/actions/workflows/tests.yml/badge.svg)
+![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)
+
+Rimscan CLI is a standalone, database-free tool for external attack-surface
+reconnaissance of domains you are authorized to test. It discovers subdomains,
+resolves DNS and CNAME chains, audits DNS and TLS configuration, checks for common
+exposed secrets, and identifies possible subdomain takeover candidates using public
+fingerprints.
+
+**Only scan domains you own or have explicit written permission to test.**
+This tool is not a license to scan arbitrary third-party infrastructure.
+
+## Installation
+
+Requires Python 3.10 or newer.
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+source .venv/bin/activate
+python -m pip install .
+```
+
+This installs the `rimscan-cli` command. `python -m rimscan_cli` works as well.
+
+## Usage
+
+```bash
+rimscan-cli scan example.com
+rimscan-cli scan example.com --output results.json
+rimscan-cli scan example.com --authorized --secrets
+rimscan-cli scan example.com --authorized --zone-transfer --nuclei
+rimscan-cli scan example.com --quiet --fail-on high    # CI use
+```
+
+Results are written to **stdout as JSON** (or to a file with `--output`).
+The banner, progress lines and the findings summary go to **stderr**, so
+`rimscan-cli scan example.com | jq .` always receives clean JSON. Use
+`--quiet` to silence stderr completely. See [`examples/example-output.json`](examples/example-output.json)
+for the shape of the output.
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `--authorized` | Confirm you own the target or may test it. Required by `--secrets`, `--zone-transfer` and `--nuclei`. |
+| `--secrets` | Fetch a fixed list of well-known paths (`/.env`, `/config.js`, ...) and look for exposed credentials. |
+| `--zone-transfer` | Attempt an AXFR against the domain's nameservers. |
+| `--nuclei` | Run [Nuclei](https://github.com/projectdiscovery/nuclei) (installed separately) with `-etags dos,fuzz,intrusive`. |
+| `--nuclei-rate-limit N` | Nuclei requests per second (default 75, at least 1). |
+| `--include-third-party` | Let `--secrets` and `--nuclei` also probe hosts that CNAME to third-party services. Skipped by default. |
+| `--bruteforce` | Also resolve a short list of common subdomain names. |
+| `--no-certs` | Skip the TLS certificate audit. |
+| `--sources LIST` | Comma-separated enumeration sources (default: all). |
+| `--resolver IPS` | Comma-separated DNS resolver addresses. Applies to DNS lookups only; TLS and HTTP probes use the system resolver. |
+| `--timeout SECONDS` | Network timeout, greater than 0 (default 10). |
+| `-o`, `--output FILE` | Write JSON to a file instead of stdout. If the file cannot be written, the results are printed to stdout instead. |
+| `--fail-on LEVEL` | Exit with status 1 if any finding is at or above `info`, `low`, `medium`, `high` or `critical`. |
+| `-q`, `--quiet` | No banner, progress, summary or log warnings on stderr. |
+| `--no-banner` | Do not print the banner. |
+| `--verbose` | Debug logging. |
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Scan finished (and no finding reached `--fail-on`). |
+| 1 | A finding at or above the `--fail-on` severity was reported. |
+| 2 | Invalid arguments, a missing `--authorized`, or an output file that could not be written. |
+| 3 | With `--fail-on`: no finding reached the threshold, but the scan was incomplete (see below). |
+| 130 | Interrupted. |
+
+A scan is **incomplete** when every enumeration source failed or timed out (and
+`--bruteforce` was not used), when a DNS lookup in the DNS audit failed (this includes the
+nameserver lookups behind `--zone-transfer`), or when at least half of the discovered hosts
+could not be resolved (timeouts or errors). A smaller number of failed lookups only adds a
+warning. In that case "no findings" does not mean the target is clean: the JSON has
+`"incomplete": true`, the reasons are listed under `warnings`, and CI runs using `--fail-on`
+exit with status 3 instead of passing silently.
+
+### Output
+
+The JSON document contains `schema_version`, `tool` (name and version), `scanned_at`,
+`domain`, `wildcard_dns`, `wildcard_filtered`, `sources` (the outcome of each enumeration
+source), `subdomains`, `resolutions`, `takeover_findings`, `dns_findings`, `warnings`,
+`incomplete`, and, when enabled, `certificate_findings`, `secret_findings`, `nuclei`,
+`active_targets` and `skipped_hosts`. Secret values are redacted in the output: a match is
+shown as its first and last four characters, and the surrounding context is built around the
+match with every credential found on that line redacted. A private-key finding shows its
+`-----BEGIN ... PRIVATE KEY-----` header in full, because the header is public and tells you
+what kind of key was exposed; any key material that follows it on the same line is replaced by
+`[...]`.
+
+## Data sent to third parties
+
+To find subdomains, the target domain name is sent to these public services:
+
+- [crt.sh](https://crt.sh)
+- [Cert Spotter](https://sslmate.com/certspotter)
+- [AlienVault OTX](https://otx.alienvault.com)
+- [RapidDNS](https://rapiddns.io)
+- [Wayback Machine](https://web.archive.org)
+- [Anubis (jldc.me)](https://jldc.me)
+
+Use `--sources` to choose a subset. The tool identifies itself with the
+User-Agent `rimscan-cli/<version> (+https://rimscan.cloud)`. Nothing is sent
+to Rimscan or any other server.
+
+## Scope and safety
+
+This tool combines public data sources with direct network checks:
+
+- **Default scan:** DNS lookups, TLS handshakes with discovered hosts, and at
+  most one HTTP request (HTTPS, then HTTP) to hosts whose CNAME points at a known
+  third-party service, to check takeover fingerprints. These requests are not retried and
+  redirects are not followed.
+- **`--bruteforce`:** DNS lookups for a short wordlist.
+- **`--secrets`:** GET requests for a fixed list of common paths on every selected host
+  (redirects are not followed). A request that fails, including one that breaks while its
+  body is being read, only skips that path.
+- **`--zone-transfer`:** AXFR requests to the domain's nameservers, using each nameserver's
+  A records, or its AAAA records if it has none.
+- **`--nuclei`:** the separately installed Nuclei scanner, which sends active
+  probes. Excluding the `dos`, `fuzz` and `intrusive` tags is not a guarantee
+  that every template is passive.
+
+Safeguards that apply to every active step:
+
+- Hosts that resolve to a non-public address (loopback, private, link-local) are never
+  probed, so a subdomain pointed at `127.0.0.1` or a cloud metadata address cannot make the
+  tool contact internal services.
+- `--secrets` and `--nuclei` skip hosts that CNAME to a known third-party service
+  (the takeover fingerprints plus a built-in list of hosting platforms such as GitHub Pages,
+  Heroku, Netlify and Shopify), because those servers are not yours. Pass
+  `--include-third-party` only if you are authorized to test them. The list of hosts that
+  were probed or skipped is in `active_targets` and `skipped_hosts`. The built-in list also
+  contains large cloud providers (for example CloudFront, AWS load balancers and Azure web
+  apps), so on a target that is mostly hosted there the default active scan can cover only a
+  few hosts. Check `skipped_hosts.third_party` before reading "no findings" as "nothing
+  exposed".
+- `--zone-transfer` never sends a request to a nameserver whose address is non-public.
+- Redirect responses are never treated as file content by the secret scan.
+- A server-supplied `Retry-After` header is ignored, so a scanned host cannot stall the tool
+  by asking it to wait.
+- Caps: the TLS audit covers at most 100 hosts and the secret scan at most 50; a warning is
+  added to the JSON `warnings` (and logged) when a cap truncates the list.
+
+Use it only against targets you are explicitly authorized to test. Respect
+provider terms, rate limits, and the scope of the authorization you received.
+
+The standalone CLI does not include Katana crawling, deep-scan tags, fuzzing,
+SQL injection or XSS templates, SaaS authentication, billing, quotas,
+notifications, a dashboard, Postgres, Redis, or Celery.
+
+## Limitations and false positives
+
+- **Passive enumeration is incomplete.** Sources only know names that appear in certificate
+  transparency logs, passive DNS or web archives. Hosts without a certificate history are
+  not found.
+- **Takeover results are candidates, not proofs.** `vulnerable` means a fingerprint matched;
+  `likely` means the CNAME points at a takeover-prone service or dangles without a
+  confirming fingerprint. Verify manually before reporting. Detection works by CNAME suffix:
+  services identified by other means (for example nameserver delegation to DigitalOcean)
+  and S3 website endpoints are not covered.
+- **Wildcard DNS.** Answers that match the zone's wildcard are filtered out. A real host that
+  shares its addresses or CNAME target with the wildcard is filtered too; the number of
+  filtered hosts is reported as `wildcard_filtered`.
+- **DNS audit.** SPF and DMARC are checked at the domain you pass. For a subdomain, DMARC is
+  looked up at each parent down to two labels, which can be wrong under multi-label public
+  suffixes such as `co.uk`.
+- **TLS audit.** Verification uses the certifi CA bundle, a TLS 1.2 floor and non-strict
+  X.509 checking, so results are the same on every supported Python version. Findings can
+  still differ from what a browser with another trust store reports.
+- **Secret scan.** It looks at a fixed list of paths only. The 40-character AWS secret
+  pattern is reported only when "aws" or "secret" appears next to it and its entropy is high.
+- **Enumeration sources fail often** (rate limits are common). Check `sources` and
+  `warnings` in the output. The crt.sh response is read up to 50 MB; for a domain with more
+  certificates than that, the source is reported as failed instead of returning a partial list.
+- **DNS rebinding.** Non-public addresses are rejected using the lookup done during the scan.
+  A host's DNS could answer differently when the probe connects; the tool does not pin the
+  connection to the checked address.
+
+## Rimscan, the hosted platform
+
+`rimscan-cli` runs locally, on demand, and performs one-off reconnaissance.
+
+[Rimscan](https://rimscan.cloud) is a hosted web platform built on the same reconnaissance
+engine. Instead of running commands, you add a domain in a dashboard. The platform adds:
+
+- **Continuous monitoring** on the Pro plan: targets are re-scanned automatically every
+  two days.
+- **Deep Scan** (Pro): active crawling with Katana and payload-based testing for issues such
+  as SQL injection and XSS. This is intentionally outside the scope of this CLI.
+- **A dashboard** with scan history and findings, severity and CVE information, and a
+  per-finding triage status.
+
+See [rimscan.cloud](https://rimscan.cloud) for current plans and availability.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m ruff check .
+python -m pytest
+```
+
+The test suite runs offline: all network and DNS access is mocked.
+
+## License
+
+This project is open source under the [Apache License 2.0](LICENSE). See
+[LICENSE](LICENSE) for the complete license text. The takeover fingerprints are
+sourced from [can-i-take-over-xyz](https://github.com/EdOverflow/can-i-take-over-xyz);
+see [NOTICE](NOTICE) and review that project's terms before redistributing the fingerprint data.