scopez 0.2.0__tar.gz → 0.3.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 (42) hide show
  1. scopez-0.3.0/AGENTS.md +68 -0
  2. {scopez-0.2.0 → scopez-0.3.0}/LICENSE +1 -1
  3. {scopez-0.2.0/src/scopez.egg-info → scopez-0.3.0}/PKG-INFO +38 -31
  4. {scopez-0.2.0 → scopez-0.3.0}/README.md +22 -19
  5. {scopez-0.2.0 → scopez-0.3.0}/pyproject.toml +29 -21
  6. scopez-0.3.0/src/__version__.py +1 -0
  7. scopez-0.3.0/src/analysis.py +367 -0
  8. scopez-0.3.0/src/main.py +365 -0
  9. {scopez-0.2.0 → scopez-0.3.0}/src/models.py +3 -15
  10. {scopez-0.2.0 → scopez-0.3.0/src/scopez.egg-info}/PKG-INFO +38 -31
  11. {scopez-0.2.0 → scopez-0.3.0}/src/scopez.egg-info/SOURCES.txt +2 -4
  12. scopez-0.3.0/src/scopez.egg-info/requires.txt +14 -0
  13. {scopez-0.2.0 → scopez-0.3.0}/src/scopez.egg-info/top_level.txt +1 -1
  14. {scopez-0.2.0 → scopez-0.3.0}/src/targets.py +75 -110
  15. {scopez-0.2.0 → scopez-0.3.0}/src/utils.py +21 -0
  16. {scopez-0.2.0 → scopez-0.3.0}/src/validation.py +2 -15
  17. {scopez-0.2.0 → scopez-0.3.0}/src/verbose.py +5 -4
  18. {scopez-0.2.0 → scopez-0.3.0}/src/visualization.py +22 -8
  19. scopez-0.2.0/.github/workflows/publish.yml +0 -37
  20. scopez-0.2.0/.github/workflows/ruff.yml +0 -24
  21. scopez-0.2.0/.pre-commit-config.yaml +0 -9
  22. scopez-0.2.0/src/__version__.py +0 -1
  23. scopez-0.2.0/src/analysis.py +0 -399
  24. scopez-0.2.0/src/main.py +0 -295
  25. scopez-0.2.0/src/scopez.egg-info/requires.txt +0 -10
  26. {scopez-0.2.0 → scopez-0.3.0}/.github/logo.svg +0 -0
  27. {scopez-0.2.0 → scopez-0.3.0}/.github/usage.png +0 -0
  28. {scopez-0.2.0 → scopez-0.3.0}/.gitignore +0 -0
  29. {scopez-0.2.0 → scopez-0.3.0}/.scripts/build_macos.sh +0 -0
  30. {scopez-0.2.0 → scopez-0.3.0}/.scripts/change_version.sh +0 -0
  31. {scopez-0.2.0 → scopez-0.3.0}/SECURITY.md +0 -0
  32. {scopez-0.2.0 → scopez-0.3.0}/setup.cfg +0 -0
  33. {scopez-0.2.0 → scopez-0.3.0}/src/__init__.py +0 -0
  34. {scopez-0.2.0 → scopez-0.3.0}/src/icons/404.png +0 -0
  35. {scopez-0.2.0 → scopez-0.3.0}/src/icons/cidr.png +0 -0
  36. {scopez-0.2.0 → scopez-0.3.0}/src/icons/fqdn.png +0 -0
  37. {scopez-0.2.0 → scopez-0.3.0}/src/icons/ipv4.png +0 -0
  38. {scopez-0.2.0 → scopez-0.3.0}/src/icons/target.png +0 -0
  39. {scopez-0.2.0 → scopez-0.3.0}/src/icons/url.png +0 -0
  40. /scopez-0.2.0/src/print.py → /scopez-0.3.0/src/printer.py +0 -0
  41. {scopez-0.2.0 → scopez-0.3.0}/src/scopez.egg-info/dependency_links.txt +0 -0
  42. {scopez-0.2.0 → scopez-0.3.0}/src/scopez.egg-info/entry_points.txt +0 -0
scopez-0.3.0/AGENTS.md ADDED
@@ -0,0 +1,68 @@
1
+ # AGENTS.md
2
+
3
+ Guidance for AI coding agents working in this repository.
4
+
5
+ ## Overview
6
+
7
+ Scopez verifies connectivity to target servers, reveals CDN presence, and provides detailed target insights like reachability and RDAP.
8
+
9
+ ## Key commands
10
+
11
+ ### Setup
12
+
13
+ ```bash
14
+ # Activate the virtual environment.
15
+ .venv/Scripts/Activate
16
+
17
+ # Install all the dependencies.
18
+ pip install -e .
19
+ ```
20
+
21
+ ### Run
22
+
23
+ ### Code quality
24
+
25
+ ```bash
26
+ # Format code
27
+ ruff check --fix
28
+ ```
29
+
30
+ ## Development workflow
31
+
32
+ ### Key development principles
33
+
34
+ - **Imports**
35
+ - Only `import A`.
36
+ - Don't use `from A import B`.
37
+ - Don't use `import A as a`
38
+ - At the start of a file. The order of importing is:
39
+ 1. External packages imports.
40
+ 2. Native packages imports.
41
+ 3. Current directory imnports
42
+ - **Functions**
43
+ - Don't create functions inside a function.
44
+ - Don't create helper functions unless prompted to.
45
+ - **No abbreviations**
46
+ - In variable names (`user` not `u`, `fieldMetadata` not `fm`)
47
+
48
+ ### Naming conventions
49
+
50
+ - **Variables/functions**: snake_case
51
+ - **Constants**: SCREAMING_SNAKE_CASE
52
+ - **Types/Classes**: PascalCase
53
+ - **Files/directories**: `file.py`
54
+
55
+ ### Notes
56
+
57
+ - Do not write tests.
58
+
59
+ ### Comments
60
+
61
+ - Use short-form comments (`#`)
62
+ - Explain WHY (business logic), not WHAT
63
+ - Do not comment obvious code
64
+
65
+ ### Before Making Changes
66
+
67
+ 1. Always run linting (`ruff check --fix`) after code changes.
68
+ 2. Always run the command to validate that it works.
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2025 xcalts
3
+ Copyright (c) 2026 xcalts
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -1,12 +1,12 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: scopez
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: Scopez verifies connectivity to target servers, reveals CDN presence, and provides detailed target insights like reachability and RDAP.
5
5
  Author-email: Christos Kaltsas <christos@xcalts.co>
6
6
  Maintainer-email: Christos Kaltsas <christos@xcalts.co>
7
7
  License: MIT License
8
8
 
9
- Copyright (c) 2025 xcalts
9
+ Copyright (c) 2026 xcalts
10
10
 
11
11
  Permission is hereby granted, free of charge, to any person obtaining a copy
12
12
  of this software and associated documentation files (the "Software"), to deal
@@ -34,16 +34,20 @@ Project-URL: Changelog, https://github.com/xcalts/scopez/releases
34
34
  Requires-Python: >3.11
35
35
  Description-Content-Type: text/markdown
36
36
  License-File: LICENSE
37
- Requires-Dist: Click
38
- Requires-Dist: requests
39
- Requires-Dist: rich
40
- Requires-Dist: pydantic
41
- Requires-Dist: ipwhois
42
- Requires-Dist: fqdn
43
- Requires-Dist: pandas
44
- Requires-Dist: networkx
45
- Requires-Dist: matplotlib
46
- Requires-Dist: scipy
37
+ Requires-Dist: click==8.5.0
38
+ Requires-Dist: requests==2.34.2
39
+ Requires-Dist: urllib3==2.8.0
40
+ Requires-Dist: rich==15.0.0
41
+ Requires-Dist: pydantic==2.14.2
42
+ Requires-Dist: ipwhois==1.3.0
43
+ Requires-Dist: dnspython==2.9.1
44
+ Requires-Dist: fqdn==1.6.0
45
+ Requires-Dist: pandas==3.1.0
46
+ Requires-Dist: networkx==3.7
47
+ Requires-Dist: matplotlib==3.11.2
48
+ Requires-Dist: numpy==2.5.4
49
+ Requires-Dist: pillow==13.0.0
50
+ Requires-Dist: scipy==1.18.1
47
51
  Dynamic: license-file
48
52
 
49
53
  <a id="readme-top"></a>
@@ -58,12 +62,10 @@ Dynamic: license-file
58
62
  [![MacOS][macos-shield]][macos-url]
59
63
  [![Stars][stars-shield]][stars-url]
60
64
  [![Contributors][contributors-shield]][contributors-url]
61
- [![Lint][lint-shield]][lint-url]
62
65
  [![Issues][issues-shield]][issues-url]
63
66
 
64
- <a href="https://github.com/xcalts/scopez">
65
- <img src="https://github.com/xcalts/scopez/raw/main/.github/logo.svg" alt="Logo" height="100" />
66
- </a>
67
+ <h1>Scopez</h1>
68
+
67
69
  <p align="center">
68
70
  Scopez verifies connectivity to target servers, reveals CDN presence, and provides detailed target insights like reachability and RDAP.
69
71
  <br />
@@ -97,7 +99,7 @@ uv tool install scopez
97
99
  - Unix friendly input/output
98
100
  - **Threads** support
99
101
  - Multiple input support - **STDIN/FILE/CIDR/IP/FQDN/URL**
100
- - Multiple output support - **TABLE/JSON/TXT/STDOUT**
102
+ - Multiple output formats - **TABLE/JSON** (stdout) and **PNG** network graph
101
103
  - Visualize the network using a graph
102
104
 
103
105
  <p align="right">(<a href="#readme-top">back to top</a>)</p>
@@ -121,29 +123,36 @@ INPUT:
121
123
  -exclude-file List of targets to exclude from analysis (file).
122
124
 
123
125
  OUTPUT:
124
- -output-prefix Output file prefix. Will generate <prefix>.json, <prefix>.txt, and <prefix>.png files.
126
+ -table Print the results as tables.
127
+ -json Print the results as JSON.
128
+ -visual Visualize the results as a network graph image (requires -output-file).
129
+ -output-file Output image file for -visual (e.g., network.png).
125
130
 
126
131
  TWEAK:
127
132
  -threads The max number of worker threads.
128
133
 
129
134
  OTHER:
130
135
  -help Show this message and exit.
131
- ```
132
136
 
133
- <p align="right">(<a href="#readme-top">back to top</a>)</p>
137
+ EXAMPLES:
138
+ # Analyze a mix of targets and print tables.
139
+ scopez -target 8.8.8.8,1.1.1.0/24,www.github.com,https://example.com -table
134
140
 
135
- ## Contributing
141
+ # Analyze targets from a file and print JSON lines (logs go to stderr).
142
+ scopez -list targets.txt -json > results.json
136
143
 
137
- Any contributions you make are **greatly appreciated**.
144
+ # Read targets from STDIN and keep only the public IPs with jq.
145
+ cat targets.txt | scopez -json -silent | jq -r 'select(.type == "ipv4" and .visibility == "Public") | .ipv4'
138
146
 
139
- If you have a suggestion that would make this better, please fork the repo and create a pull request.
140
- You can also simply open an issue with the tag "enhancement".
147
+ # Exclude out-of-scope targets.
148
+ scopez -list targets.txt -exclude-file out-of-scope.txt -table
141
149
 
142
- 1. Fork the Project.
143
- 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`).
144
- 3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`).
145
- 4. Push to the Branch (`git push origin feature/AmazingFeature`).
146
- 5. Open a Pull Request.
150
+ # Draw the targets, their DNS chains and IPs as a network graph.
151
+ scopez -list targets.txt -visual -output-file network.png
152
+
153
+ # Preview how the targets are parsed without analyzing them.
154
+ scopez -list targets.txt -simulate
155
+ ```
147
156
 
148
157
  <p align="right">(<a href="#readme-top">back to top</a>)</p>
149
158
 
@@ -152,8 +161,6 @@ You can also simply open an issue with the tag "enhancement".
152
161
 
153
162
  [contributors-shield]: https://img.shields.io/github/contributors/xcalts/scopez.svg?style=flat
154
163
  [contributors-url]: https://github.com/xcalts/scopez/graphs/contributors
155
- [lint-shield]: https://img.shields.io/github/actions/workflow/status/xcalts/scopez/ruff.yml?style=flat&label=ruff-lint
156
- [lint-url]: https://github.com/xcalts/scopez/actions/workflows/ruff.yml
157
164
  [stars-shield]: https://img.shields.io/github/stars/xcalts/scopez.svg?style=flat
158
165
  [stars-url]: https://github.com/xcalts/scopez/stargazers
159
166
  [issues-shield]: https://img.shields.io/github/issues/xcalts/scopez.svg?style=flat
@@ -10,12 +10,10 @@
10
10
  [![MacOS][macos-shield]][macos-url]
11
11
  [![Stars][stars-shield]][stars-url]
12
12
  [![Contributors][contributors-shield]][contributors-url]
13
- [![Lint][lint-shield]][lint-url]
14
13
  [![Issues][issues-shield]][issues-url]
15
14
 
16
- <a href="https://github.com/xcalts/scopez">
17
- <img src="https://github.com/xcalts/scopez/raw/main/.github/logo.svg" alt="Logo" height="100" />
18
- </a>
15
+ <h1>Scopez</h1>
16
+
19
17
  <p align="center">
20
18
  Scopez verifies connectivity to target servers, reveals CDN presence, and provides detailed target insights like reachability and RDAP.
21
19
  <br />
@@ -49,7 +47,7 @@ uv tool install scopez
49
47
  - Unix friendly input/output
50
48
  - **Threads** support
51
49
  - Multiple input support - **STDIN/FILE/CIDR/IP/FQDN/URL**
52
- - Multiple output support - **TABLE/JSON/TXT/STDOUT**
50
+ - Multiple output formats - **TABLE/JSON** (stdout) and **PNG** network graph
53
51
  - Visualize the network using a graph
54
52
 
55
53
  <p align="right">(<a href="#readme-top">back to top</a>)</p>
@@ -73,29 +71,36 @@ INPUT:
73
71
  -exclude-file List of targets to exclude from analysis (file).
74
72
 
75
73
  OUTPUT:
76
- -output-prefix Output file prefix. Will generate <prefix>.json, <prefix>.txt, and <prefix>.png files.
74
+ -table Print the results as tables.
75
+ -json Print the results as JSON.
76
+ -visual Visualize the results as a network graph image (requires -output-file).
77
+ -output-file Output image file for -visual (e.g., network.png).
77
78
 
78
79
  TWEAK:
79
80
  -threads The max number of worker threads.
80
81
 
81
82
  OTHER:
82
83
  -help Show this message and exit.
83
- ```
84
84
 
85
- <p align="right">(<a href="#readme-top">back to top</a>)</p>
85
+ EXAMPLES:
86
+ # Analyze a mix of targets and print tables.
87
+ scopez -target 8.8.8.8,1.1.1.0/24,www.github.com,https://example.com -table
86
88
 
87
- ## Contributing
89
+ # Analyze targets from a file and print JSON lines (logs go to stderr).
90
+ scopez -list targets.txt -json > results.json
88
91
 
89
- Any contributions you make are **greatly appreciated**.
92
+ # Read targets from STDIN and keep only the public IPs with jq.
93
+ cat targets.txt | scopez -json -silent | jq -r 'select(.type == "ipv4" and .visibility == "Public") | .ipv4'
90
94
 
91
- If you have a suggestion that would make this better, please fork the repo and create a pull request.
92
- You can also simply open an issue with the tag "enhancement".
95
+ # Exclude out-of-scope targets.
96
+ scopez -list targets.txt -exclude-file out-of-scope.txt -table
93
97
 
94
- 1. Fork the Project.
95
- 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`).
96
- 3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`).
97
- 4. Push to the Branch (`git push origin feature/AmazingFeature`).
98
- 5. Open a Pull Request.
98
+ # Draw the targets, their DNS chains and IPs as a network graph.
99
+ scopez -list targets.txt -visual -output-file network.png
100
+
101
+ # Preview how the targets are parsed without analyzing them.
102
+ scopez -list targets.txt -simulate
103
+ ```
99
104
 
100
105
  <p align="right">(<a href="#readme-top">back to top</a>)</p>
101
106
 
@@ -104,8 +109,6 @@ You can also simply open an issue with the tag "enhancement".
104
109
 
105
110
  [contributors-shield]: https://img.shields.io/github/contributors/xcalts/scopez.svg?style=flat
106
111
  [contributors-url]: https://github.com/xcalts/scopez/graphs/contributors
107
- [lint-shield]: https://img.shields.io/github/actions/workflow/status/xcalts/scopez/ruff.yml?style=flat&label=ruff-lint
108
- [lint-url]: https://github.com/xcalts/scopez/actions/workflows/ruff.yml
109
112
  [stars-shield]: https://img.shields.io/github/stars/xcalts/scopez.svg?style=flat
110
113
  [stars-url]: https://github.com/xcalts/scopez/stargazers
111
114
  [issues-shield]: https://img.shields.io/github/issues/xcalts/scopez.svg?style=flat
@@ -3,12 +3,12 @@ requires = ["setuptools", "setuptools-scm", "wheel"]
3
3
  build-backend = "setuptools.build_meta"
4
4
 
5
5
  [tool.setuptools.package-data]
6
- scopez = ["icons/*.png", "geoip2-ipv4.csv"]
6
+ scopez = ["icons/*.png"]
7
7
 
8
8
  # --- Project Settings ---
9
9
  [project]
10
10
  name = "scopez"
11
- version = "v0.2.0"
11
+ version = "0.3.0"
12
12
  description = "Scopez verifies connectivity to target servers, reveals CDN presence, and provides detailed target insights like reachability and RDAP."
13
13
  readme = "README.md"
14
14
  requires-python = ">3.11"
@@ -18,26 +18,34 @@ maintainers = [{ name = "Christos Kaltsas", email = "christos@xcalts.co" }]
18
18
 
19
19
  # --- Required Dependencies ---
20
20
  dependencies = [
21
- # Command-line interface
22
- "Click",
23
- # REST HTTP Client
24
- "requests",
21
+ # Command-line interface.
22
+ "click==8.5.0",
23
+ # REST HTTP client.
24
+ "requests==2.34.2",
25
+ # HTTP library used by requests (imported directly to silence InsecureRequestWarning).
26
+ "urllib3==2.8.0",
25
27
  # Rich text and beautiful formatting in the terminal.
26
- "rich",
27
- # Pydantic is the most widely used data validation library for Python.
28
- "pydantic",
29
- # Retrieve and parse whois data for IPv4 and IPv6 addresses.
30
- "ipwhois",
31
- # Validates fully-qualified domain names against RFC 1123, so that they are acceptable to modern bowsers.
32
- "fqdn",
33
- # A fast, powerful, flexible and easy to use open source data analysis and manipulation tool.
34
- "pandas",
35
- # Package for the creation, manipulation, and study of the structure, dynamics, and functions of complex networks.
36
- "networkx",
37
- # A comprehensive library for creating static, animated, and interactive visualizations in Python.
38
- "matplotlib",
39
- # Fundamental algorithms for scientific computing in Python.
40
- "scipy",
28
+ "rich==15.0.0",
29
+ # Data validation and models.
30
+ "pydantic==2.14.2",
31
+ # Retrieve and parse RDAP/whois data for IP addresses.
32
+ "ipwhois==1.3.0",
33
+ # DNS toolkit used to follow CNAME chains and resolve A records.
34
+ "dnspython==2.9.1",
35
+ # Validates fully-qualified domain names against RFC 1123.
36
+ "fqdn==1.6.0",
37
+ # Loads the GeoIP CSV database.
38
+ "pandas==3.1.0",
39
+ # Network graph for -visual.
40
+ "networkx==3.7",
41
+ # Renders the -visual network graph.
42
+ "matplotlib==3.11.2",
43
+ # Node positions for the -visual network graph.
44
+ "numpy==2.5.4",
45
+ # Loads the node icons for the -visual network graph.
46
+ "pillow==13.0.0",
47
+ # Required by networkx's kamada_kawai_layout (-visual).
48
+ "scipy==1.18.1",
41
49
  ]
42
50
 
43
51
  # --- URLs ---
@@ -0,0 +1 @@
1
+ __version__ = 'v0.2.1'