├── .github └── workflows │ └── python-package.yml ├── .gitignore ├── LICENSE ├── README.md ├── pyproject.toml ├── renovate.json ├── setup.cfg ├── setup.py ├── src └── dns_deep_state │ ├── __init__.py │ ├── dns.py │ ├── exceptions.py │ ├── hosts.py │ ├── registry.py │ └── report.py └── tests ├── __init__.py ├── integration ├── __init__.py ├── test_all_fine.py └── test_invalid_domain.py ├── test_dns.py ├── test_hosts.py ├── test_registry.py └── test_report.py /.github/workflows/python-package.yml: -------------------------------------------------------------------------------- 1 | # This workflow will install Python dependencies, run tests and lint with a variety of Python versions 2 | # For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions 3 | 4 | name: Python package 5 | 6 | on: [push, pull_request] 7 | 8 | jobs: 9 | # The code only needs to be linted against one python version. We'll use the 10 | # latest one 11 | lint: 12 | runs-on: ubuntu-latest 13 | strategy: 14 | fail-fast: false 15 | matrix: 16 | python-version: [3.9] 17 | 18 | steps: 19 | - uses: actions/checkout@v4 20 | - name: Set up Python ${{ matrix.python-version }} 21 | uses: actions/setup-python@v5 22 | with: 23 | python-version: ${{ matrix.python-version }} 24 | - name: Install flake8 25 | run: | 26 | python -m pip install --upgrade pip 27 | python -m pip install .[lint] 28 | - name: Display versions 29 | run: | 30 | python -c "import sys; print(sys.version)" 31 | flake8 --version 32 | - name: Lint with flake8 33 | run: | 34 | flake8 . --count --statistics 35 | 36 | types: 37 | # We only need to perform static type analysis on one version of python 38 | runs-on: ubuntu-latest 39 | needs: lint 40 | strategy: 41 | fail-fast: false 42 | matrix: 43 | python-version: [3.9] 44 | 45 | steps: 46 | - uses: actions/checkout@v4 47 | - name: Set up Python ${{ matrix.python-version }} 48 | uses: actions/setup-python@v5 49 | with: 50 | python-version: ${{ matrix.python-version }} 51 | - name: Install mypy 52 | run: | 53 | python -m pip install --upgrade pip 54 | python -m pip install .[types] 55 | - name: Display versions 56 | run: | 57 | python -c "import sys; print(sys.version)" 58 | mypy --version 59 | - name: Static type analysis 60 | run: | 61 | mypy src/dns_deep_state tests/ 62 | 63 | test: 64 | runs-on: ubuntu-latest 65 | needs: types 66 | strategy: 67 | fail-fast: false 68 | matrix: 69 | python-version: [3.7, 3.8, 3.9] 70 | 71 | steps: 72 | - uses: actions/checkout@v4 73 | - name: Set up Python ${{ matrix.python-version }} 74 | uses: actions/setup-python@v5 75 | with: 76 | python-version: ${{ matrix.python-version }} 77 | - name: Display Python version 78 | run: python -c "import sys; print(sys.version)" 79 | - name: Install dependencies 80 | run: | 81 | python -m pip install --upgrade pip 82 | # This will install pytest 83 | python -m pip install .[test] 84 | - name: Test with pytest 85 | run: | 86 | pytest 87 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.pyc 2 | *.pyo 3 | *.egg-info 4 | build/ 5 | dist/ 6 | .coverage 7 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | The GNU General Public License is a free, copyleft license for 11 | software and other kinds of works. 12 | 13 | The licenses for most software and other practical works are designed 14 | to take away your freedom to share and change the works. By contrast, 15 | the GNU General Public License is intended to guarantee your freedom to 16 | share and change all versions of a program--to make sure it remains free 17 | software for all its users. We, the Free Software Foundation, use the 18 | GNU General Public License for most of our software; it applies also to 19 | any other work released this way by its authors. You can apply it to 20 | your programs, too. 21 | 22 | When we speak of free software, we are referring to freedom, not 23 | price. Our General Public Licenses are designed to make sure that you 24 | have the freedom to distribute copies of free software (and charge for 25 | them if you wish), that you receive source code or can get it if you 26 | want it, that you can change the software or use pieces of it in new 27 | free programs, and that you know you can do these things. 28 | 29 | To protect your rights, we need to prevent others from denying you 30 | these rights or asking you to surrender the rights. Therefore, you have 31 | certain responsibilities if you distribute copies of the software, or if 32 | you modify it: responsibilities to respect the freedom of others. 33 | 34 | For example, if you distribute copies of such a program, whether 35 | gratis or for a fee, you must pass on to the recipients the same 36 | freedoms that you received. You must make sure that they, too, receive 37 | or can get the source code. And you must show them these terms so they 38 | know their rights. 39 | 40 | Developers that use the GNU GPL protect your rights with two steps: 41 | (1) assert copyright on the software, and (2) offer you this License 42 | giving you legal permission to copy, distribute and/or modify it. 43 | 44 | For the developers' and authors' protection, the GPL clearly explains 45 | that there is no warranty for this free software. For both users' and 46 | authors' sake, the GPL requires that modified versions be marked as 47 | changed, so that their problems will not be attributed erroneously to 48 | authors of previous versions. 49 | 50 | Some devices are designed to deny users access to install or run 51 | modified versions of the software inside them, although the manufacturer 52 | can do so. This is fundamentally incompatible with the aim of 53 | protecting users' freedom to change the software. The systematic 54 | pattern of such abuse occurs in the area of products for individuals to 55 | use, which is precisely where it is most unacceptable. Therefore, we 56 | have designed this version of the GPL to prohibit the practice for those 57 | products. If such problems arise substantially in other domains, we 58 | stand ready to extend this provision to those domains in future versions 59 | of the GPL, as needed to protect the freedom of users. 60 | 61 | Finally, every program is threatened constantly by software patents. 62 | States should not allow patents to restrict development and use of 63 | software on general-purpose computers, but in those that do, we wish to 64 | avoid the special danger that patents applied to a free program could 65 | make it effectively proprietary. To prevent this, the GPL assures that 66 | patents cannot be used to render the program non-free. 67 | 68 | The precise terms and conditions for copying, distribution and 69 | modification follow. 70 | 71 | TERMS AND CONDITIONS 72 | 73 | 0. Definitions. 74 | 75 | "This License" refers to version 3 of the GNU General Public License. 76 | 77 | "Copyright" also means copyright-like laws that apply to other kinds of 78 | works, such as semiconductor masks. 79 | 80 | "The Program" refers to any copyrightable work licensed under this 81 | License. Each licensee is addressed as "you". "Licensees" and 82 | "recipients" may be individuals or organizations. 83 | 84 | To "modify" a work means to copy from or adapt all or part of the work 85 | in a fashion requiring copyright permission, other than the making of an 86 | exact copy. The resulting work is called a "modified version" of the 87 | earlier work or a work "based on" the earlier work. 88 | 89 | A "covered work" means either the unmodified Program or a work based 90 | on the Program. 91 | 92 | To "propagate" a work means to do anything with it that, without 93 | permission, would make you directly or secondarily liable for 94 | infringement under applicable copyright law, except executing it on a 95 | computer or modifying a private copy. Propagation includes copying, 96 | distribution (with or without modification), making available to the 97 | public, and in some countries other activities as well. 98 | 99 | To "convey" a work means any kind of propagation that enables other 100 | parties to make or receive copies. Mere interaction with a user through 101 | a computer network, with no transfer of a copy, is not conveying. 102 | 103 | An interactive user interface displays "Appropriate Legal Notices" 104 | to the extent that it includes a convenient and prominently visible 105 | feature that (1) displays an appropriate copyright notice, and (2) 106 | tells the user that there is no warranty for the work (except to the 107 | extent that warranties are provided), that licensees may convey the 108 | work under this License, and how to view a copy of this License. If 109 | the interface presents a list of user commands or options, such as a 110 | menu, a prominent item in the list meets this criterion. 111 | 112 | 1. Source Code. 113 | 114 | The "source code" for a work means the preferred form of the work 115 | for making modifications to it. "Object code" means any non-source 116 | form of a work. 117 | 118 | A "Standard Interface" means an interface that either is an official 119 | standard defined by a recognized standards body, or, in the case of 120 | interfaces specified for a particular programming language, one that 121 | is widely used among developers working in that language. 122 | 123 | The "System Libraries" of an executable work include anything, other 124 | than the work as a whole, that (a) is included in the normal form of 125 | packaging a Major Component, but which is not part of that Major 126 | Component, and (b) serves only to enable use of the work with that 127 | Major Component, or to implement a Standard Interface for which an 128 | implementation is available to the public in source code form. A 129 | "Major Component", in this context, means a major essential component 130 | (kernel, window system, and so on) of the specific operating system 131 | (if any) on which the executable work runs, or a compiler used to 132 | produce the work, or an object code interpreter used to run it. 133 | 134 | The "Corresponding Source" for a work in object code form means all 135 | the source code needed to generate, install, and (for an executable 136 | work) run the object code and to modify the work, including scripts to 137 | control those activities. However, it does not include the work's 138 | System Libraries, or general-purpose tools or generally available free 139 | programs which are used unmodified in performing those activities but 140 | which are not part of the work. For example, Corresponding Source 141 | includes interface definition files associated with source files for 142 | the work, and the source code for shared libraries and dynamically 143 | linked subprograms that the work is specifically designed to require, 144 | such as by intimate data communication or control flow between those 145 | subprograms and other parts of the work. 146 | 147 | The Corresponding Source need not include anything that users 148 | can regenerate automatically from other parts of the Corresponding 149 | Source. 150 | 151 | The Corresponding Source for a work in source code form is that 152 | same work. 153 | 154 | 2. Basic Permissions. 155 | 156 | All rights granted under this License are granted for the term of 157 | copyright on the Program, and are irrevocable provided the stated 158 | conditions are met. This License explicitly affirms your unlimited 159 | permission to run the unmodified Program. The output from running a 160 | covered work is covered by this License only if the output, given its 161 | content, constitutes a covered work. This License acknowledges your 162 | rights of fair use or other equivalent, as provided by copyright law. 163 | 164 | You may make, run and propagate covered works that you do not 165 | convey, without conditions so long as your license otherwise remains 166 | in force. You may convey covered works to others for the sole purpose 167 | of having them make modifications exclusively for you, or provide you 168 | with facilities for running those works, provided that you comply with 169 | the terms of this License in conveying all material for which you do 170 | not control copyright. Those thus making or running the covered works 171 | for you must do so exclusively on your behalf, under your direction 172 | and control, on terms that prohibit them from making any copies of 173 | your copyrighted material outside their relationship with you. 174 | 175 | Conveying under any other circumstances is permitted solely under 176 | the conditions stated below. Sublicensing is not allowed; section 10 177 | makes it unnecessary. 178 | 179 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 180 | 181 | No covered work shall be deemed part of an effective technological 182 | measure under any applicable law fulfilling obligations under article 183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 184 | similar laws prohibiting or restricting circumvention of such 185 | measures. 186 | 187 | When you convey a covered work, you waive any legal power to forbid 188 | circumvention of technological measures to the extent such circumvention 189 | is effected by exercising rights under this License with respect to 190 | the covered work, and you disclaim any intention to limit operation or 191 | modification of the work as a means of enforcing, against the work's 192 | users, your or third parties' legal rights to forbid circumvention of 193 | technological measures. 194 | 195 | 4. Conveying Verbatim Copies. 196 | 197 | You may convey verbatim copies of the Program's source code as you 198 | receive it, in any medium, provided that you conspicuously and 199 | appropriately publish on each copy an appropriate copyright notice; 200 | keep intact all notices stating that this License and any 201 | non-permissive terms added in accord with section 7 apply to the code; 202 | keep intact all notices of the absence of any warranty; and give all 203 | recipients a copy of this License along with the Program. 204 | 205 | You may charge any price or no price for each copy that you convey, 206 | and you may offer support or warranty protection for a fee. 207 | 208 | 5. Conveying Modified Source Versions. 209 | 210 | You may convey a work based on the Program, or the modifications to 211 | produce it from the Program, in the form of source code under the 212 | terms of section 4, provided that you also meet all of these conditions: 213 | 214 | a) The work must carry prominent notices stating that you modified 215 | it, and giving a relevant date. 216 | 217 | b) The work must carry prominent notices stating that it is 218 | released under this License and any conditions added under section 219 | 7. This requirement modifies the requirement in section 4 to 220 | "keep intact all notices". 221 | 222 | c) You must license the entire work, as a whole, under this 223 | License to anyone who comes into possession of a copy. This 224 | License will therefore apply, along with any applicable section 7 225 | additional terms, to the whole of the work, and all its parts, 226 | regardless of how they are packaged. This License gives no 227 | permission to license the work in any other way, but it does not 228 | invalidate such permission if you have separately received it. 229 | 230 | d) If the work has interactive user interfaces, each must display 231 | Appropriate Legal Notices; however, if the Program has interactive 232 | interfaces that do not display Appropriate Legal Notices, your 233 | work need not make them do so. 234 | 235 | A compilation of a covered work with other separate and independent 236 | works, which are not by their nature extensions of the covered work, 237 | and which are not combined with it such as to form a larger program, 238 | in or on a volume of a storage or distribution medium, is called an 239 | "aggregate" if the compilation and its resulting copyright are not 240 | used to limit the access or legal rights of the compilation's users 241 | beyond what the individual works permit. Inclusion of a covered work 242 | in an aggregate does not cause this License to apply to the other 243 | parts of the aggregate. 244 | 245 | 6. Conveying Non-Source Forms. 246 | 247 | You may convey a covered work in object code form under the terms 248 | of sections 4 and 5, provided that you also convey the 249 | machine-readable Corresponding Source under the terms of this License, 250 | in one of these ways: 251 | 252 | a) Convey the object code in, or embodied in, a physical product 253 | (including a physical distribution medium), accompanied by the 254 | Corresponding Source fixed on a durable physical medium 255 | customarily used for software interchange. 256 | 257 | b) Convey the object code in, or embodied in, a physical product 258 | (including a physical distribution medium), accompanied by a 259 | written offer, valid for at least three years and valid for as 260 | long as you offer spare parts or customer support for that product 261 | model, to give anyone who possesses the object code either (1) a 262 | copy of the Corresponding Source for all the software in the 263 | product that is covered by this License, on a durable physical 264 | medium customarily used for software interchange, for a price no 265 | more than your reasonable cost of physically performing this 266 | conveying of source, or (2) access to copy the 267 | Corresponding Source from a network server at no charge. 268 | 269 | c) Convey individual copies of the object code with a copy of the 270 | written offer to provide the Corresponding Source. This 271 | alternative is allowed only occasionally and noncommercially, and 272 | only if you received the object code with such an offer, in accord 273 | with subsection 6b. 274 | 275 | d) Convey the object code by offering access from a designated 276 | place (gratis or for a charge), and offer equivalent access to the 277 | Corresponding Source in the same way through the same place at no 278 | further charge. You need not require recipients to copy the 279 | Corresponding Source along with the object code. If the place to 280 | copy the object code is a network server, the Corresponding Source 281 | may be on a different server (operated by you or a third party) 282 | that supports equivalent copying facilities, provided you maintain 283 | clear directions next to the object code saying where to find the 284 | Corresponding Source. Regardless of what server hosts the 285 | Corresponding Source, you remain obligated to ensure that it is 286 | available for as long as needed to satisfy these requirements. 287 | 288 | e) Convey the object code using peer-to-peer transmission, provided 289 | you inform other peers where the object code and Corresponding 290 | Source of the work are being offered to the general public at no 291 | charge under subsection 6d. 292 | 293 | A separable portion of the object code, whose source code is excluded 294 | from the Corresponding Source as a System Library, need not be 295 | included in conveying the object code work. 296 | 297 | A "User Product" is either (1) a "consumer product", which means any 298 | tangible personal property which is normally used for personal, family, 299 | or household purposes, or (2) anything designed or sold for incorporation 300 | into a dwelling. In determining whether a product is a consumer product, 301 | doubtful cases shall be resolved in favor of coverage. For a particular 302 | product received by a particular user, "normally used" refers to a 303 | typical or common use of that class of product, regardless of the status 304 | of the particular user or of the way in which the particular user 305 | actually uses, or expects or is expected to use, the product. A product 306 | is a consumer product regardless of whether the product has substantial 307 | commercial, industrial or non-consumer uses, unless such uses represent 308 | the only significant mode of use of the product. 309 | 310 | "Installation Information" for a User Product means any methods, 311 | procedures, authorization keys, or other information required to install 312 | and execute modified versions of a covered work in that User Product from 313 | a modified version of its Corresponding Source. The information must 314 | suffice to ensure that the continued functioning of the modified object 315 | code is in no case prevented or interfered with solely because 316 | modification has been made. 317 | 318 | If you convey an object code work under this section in, or with, or 319 | specifically for use in, a User Product, and the conveying occurs as 320 | part of a transaction in which the right of possession and use of the 321 | User Product is transferred to the recipient in perpetuity or for a 322 | fixed term (regardless of how the transaction is characterized), the 323 | Corresponding Source conveyed under this section must be accompanied 324 | by the Installation Information. But this requirement does not apply 325 | if neither you nor any third party retains the ability to install 326 | modified object code on the User Product (for example, the work has 327 | been installed in ROM). 328 | 329 | The requirement to provide Installation Information does not include a 330 | requirement to continue to provide support service, warranty, or updates 331 | for a work that has been modified or installed by the recipient, or for 332 | the User Product in which it has been modified or installed. Access to a 333 | network may be denied when the modification itself materially and 334 | adversely affects the operation of the network or violates the rules and 335 | protocols for communication across the network. 336 | 337 | Corresponding Source conveyed, and Installation Information provided, 338 | in accord with this section must be in a format that is publicly 339 | documented (and with an implementation available to the public in 340 | source code form), and must require no special password or key for 341 | unpacking, reading or copying. 342 | 343 | 7. Additional Terms. 344 | 345 | "Additional permissions" are terms that supplement the terms of this 346 | License by making exceptions from one or more of its conditions. 347 | Additional permissions that are applicable to the entire Program shall 348 | be treated as though they were included in this License, to the extent 349 | that they are valid under applicable law. If additional permissions 350 | apply only to part of the Program, that part may be used separately 351 | under those permissions, but the entire Program remains governed by 352 | this License without regard to the additional permissions. 353 | 354 | When you convey a copy of a covered work, you may at your option 355 | remove any additional permissions from that copy, or from any part of 356 | it. (Additional permissions may be written to require their own 357 | removal in certain cases when you modify the work.) You may place 358 | additional permissions on material, added by you to a covered work, 359 | for which you have or can give appropriate copyright permission. 360 | 361 | Notwithstanding any other provision of this License, for material you 362 | add to a covered work, you may (if authorized by the copyright holders of 363 | that material) supplement the terms of this License with terms: 364 | 365 | a) Disclaiming warranty or limiting liability differently from the 366 | terms of sections 15 and 16 of this License; or 367 | 368 | b) Requiring preservation of specified reasonable legal notices or 369 | author attributions in that material or in the Appropriate Legal 370 | Notices displayed by works containing it; or 371 | 372 | c) Prohibiting misrepresentation of the origin of that material, or 373 | requiring that modified versions of such material be marked in 374 | reasonable ways as different from the original version; or 375 | 376 | d) Limiting the use for publicity purposes of names of licensors or 377 | authors of the material; or 378 | 379 | e) Declining to grant rights under trademark law for use of some 380 | trade names, trademarks, or service marks; or 381 | 382 | f) Requiring indemnification of licensors and authors of that 383 | material by anyone who conveys the material (or modified versions of 384 | it) with contractual assumptions of liability to the recipient, for 385 | any liability that these contractual assumptions directly impose on 386 | those licensors and authors. 387 | 388 | All other non-permissive additional terms are considered "further 389 | restrictions" within the meaning of section 10. If the Program as you 390 | received it, or any part of it, contains a notice stating that it is 391 | governed by this License along with a term that is a further 392 | restriction, you may remove that term. If a license document contains 393 | a further restriction but permits relicensing or conveying under this 394 | License, you may add to a covered work material governed by the terms 395 | of that license document, provided that the further restriction does 396 | not survive such relicensing or conveying. 397 | 398 | If you add terms to a covered work in accord with this section, you 399 | must place, in the relevant source files, a statement of the 400 | additional terms that apply to those files, or a notice indicating 401 | where to find the applicable terms. 402 | 403 | Additional terms, permissive or non-permissive, may be stated in the 404 | form of a separately written license, or stated as exceptions; 405 | the above requirements apply either way. 406 | 407 | 8. Termination. 408 | 409 | You may not propagate or modify a covered work except as expressly 410 | provided under this License. Any attempt otherwise to propagate or 411 | modify it is void, and will automatically terminate your rights under 412 | this License (including any patent licenses granted under the third 413 | paragraph of section 11). 414 | 415 | However, if you cease all violation of this License, then your 416 | license from a particular copyright holder is reinstated (a) 417 | provisionally, unless and until the copyright holder explicitly and 418 | finally terminates your license, and (b) permanently, if the copyright 419 | holder fails to notify you of the violation by some reasonable means 420 | prior to 60 days after the cessation. 421 | 422 | Moreover, your license from a particular copyright holder is 423 | reinstated permanently if the copyright holder notifies you of the 424 | violation by some reasonable means, this is the first time you have 425 | received notice of violation of this License (for any work) from that 426 | copyright holder, and you cure the violation prior to 30 days after 427 | your receipt of the notice. 428 | 429 | Termination of your rights under this section does not terminate the 430 | licenses of parties who have received copies or rights from you under 431 | this License. If your rights have been terminated and not permanently 432 | reinstated, you do not qualify to receive new licenses for the same 433 | material under section 10. 434 | 435 | 9. Acceptance Not Required for Having Copies. 436 | 437 | You are not required to accept this License in order to receive or 438 | run a copy of the Program. Ancillary propagation of a covered work 439 | occurring solely as a consequence of using peer-to-peer transmission 440 | to receive a copy likewise does not require acceptance. However, 441 | nothing other than this License grants you permission to propagate or 442 | modify any covered work. These actions infringe copyright if you do 443 | not accept this License. Therefore, by modifying or propagating a 444 | covered work, you indicate your acceptance of this License to do so. 445 | 446 | 10. Automatic Licensing of Downstream Recipients. 447 | 448 | Each time you convey a covered work, the recipient automatically 449 | receives a license from the original licensors, to run, modify and 450 | propagate that work, subject to this License. You are not responsible 451 | for enforcing compliance by third parties with this License. 452 | 453 | An "entity transaction" is a transaction transferring control of an 454 | organization, or substantially all assets of one, or subdividing an 455 | organization, or merging organizations. If propagation of a covered 456 | work results from an entity transaction, each party to that 457 | transaction who receives a copy of the work also receives whatever 458 | licenses to the work the party's predecessor in interest had or could 459 | give under the previous paragraph, plus a right to possession of the 460 | Corresponding Source of the work from the predecessor in interest, if 461 | the predecessor has it or can get it with reasonable efforts. 462 | 463 | You may not impose any further restrictions on the exercise of the 464 | rights granted or affirmed under this License. For example, you may 465 | not impose a license fee, royalty, or other charge for exercise of 466 | rights granted under this License, and you may not initiate litigation 467 | (including a cross-claim or counterclaim in a lawsuit) alleging that 468 | any patent claim is infringed by making, using, selling, offering for 469 | sale, or importing the Program or any portion of it. 470 | 471 | 11. Patents. 472 | 473 | A "contributor" is a copyright holder who authorizes use under this 474 | License of the Program or a work on which the Program is based. The 475 | work thus licensed is called the contributor's "contributor version". 476 | 477 | A contributor's "essential patent claims" are all patent claims 478 | owned or controlled by the contributor, whether already acquired or 479 | hereafter acquired, that would be infringed by some manner, permitted 480 | by this License, of making, using, or selling its contributor version, 481 | but do not include claims that would be infringed only as a 482 | consequence of further modification of the contributor version. For 483 | purposes of this definition, "control" includes the right to grant 484 | patent sublicenses in a manner consistent with the requirements of 485 | this License. 486 | 487 | Each contributor grants you a non-exclusive, worldwide, royalty-free 488 | patent license under the contributor's essential patent claims, to 489 | make, use, sell, offer for sale, import and otherwise run, modify and 490 | propagate the contents of its contributor version. 491 | 492 | In the following three paragraphs, a "patent license" is any express 493 | agreement or commitment, however denominated, not to enforce a patent 494 | (such as an express permission to practice a patent or covenant not to 495 | sue for patent infringement). To "grant" such a patent license to a 496 | party means to make such an agreement or commitment not to enforce a 497 | patent against the party. 498 | 499 | If you convey a covered work, knowingly relying on a patent license, 500 | and the Corresponding Source of the work is not available for anyone 501 | to copy, free of charge and under the terms of this License, through a 502 | publicly available network server or other readily accessible means, 503 | then you must either (1) cause the Corresponding Source to be so 504 | available, or (2) arrange to deprive yourself of the benefit of the 505 | patent license for this particular work, or (3) arrange, in a manner 506 | consistent with the requirements of this License, to extend the patent 507 | license to downstream recipients. "Knowingly relying" means you have 508 | actual knowledge that, but for the patent license, your conveying the 509 | covered work in a country, or your recipient's use of the covered work 510 | in a country, would infringe one or more identifiable patents in that 511 | country that you have reason to believe are valid. 512 | 513 | If, pursuant to or in connection with a single transaction or 514 | arrangement, you convey, or propagate by procuring conveyance of, a 515 | covered work, and grant a patent license to some of the parties 516 | receiving the covered work authorizing them to use, propagate, modify 517 | or convey a specific copy of the covered work, then the patent license 518 | you grant is automatically extended to all recipients of the covered 519 | work and works based on it. 520 | 521 | A patent license is "discriminatory" if it does not include within 522 | the scope of its coverage, prohibits the exercise of, or is 523 | conditioned on the non-exercise of one or more of the rights that are 524 | specifically granted under this License. You may not convey a covered 525 | work if you are a party to an arrangement with a third party that is 526 | in the business of distributing software, under which you make payment 527 | to the third party based on the extent of your activity of conveying 528 | the work, and under which the third party grants, to any of the 529 | parties who would receive the covered work from you, a discriminatory 530 | patent license (a) in connection with copies of the covered work 531 | conveyed by you (or copies made from those copies), or (b) primarily 532 | for and in connection with specific products or compilations that 533 | contain the covered work, unless you entered into that arrangement, 534 | or that patent license was granted, prior to 28 March 2007. 535 | 536 | Nothing in this License shall be construed as excluding or limiting 537 | any implied license or other defenses to infringement that may 538 | otherwise be available to you under applicable patent law. 539 | 540 | 12. No Surrender of Others' Freedom. 541 | 542 | If conditions are imposed on you (whether by court order, agreement or 543 | otherwise) that contradict the conditions of this License, they do not 544 | excuse you from the conditions of this License. If you cannot convey a 545 | covered work so as to satisfy simultaneously your obligations under this 546 | License and any other pertinent obligations, then as a consequence you may 547 | not convey it at all. For example, if you agree to terms that obligate you 548 | to collect a royalty for further conveying from those to whom you convey 549 | the Program, the only way you could satisfy both those terms and this 550 | License would be to refrain entirely from conveying the Program. 551 | 552 | 13. Use with the GNU Affero General Public License. 553 | 554 | Notwithstanding any other provision of this License, you have 555 | permission to link or combine any covered work with a work licensed 556 | under version 3 of the GNU Affero General Public License into a single 557 | combined work, and to convey the resulting work. The terms of this 558 | License will continue to apply to the part which is the covered work, 559 | but the special requirements of the GNU Affero General Public License, 560 | section 13, concerning interaction through a network will apply to the 561 | combination as such. 562 | 563 | 14. Revised Versions of this License. 564 | 565 | The Free Software Foundation may publish revised and/or new versions of 566 | the GNU General Public License from time to time. Such new versions will 567 | be similar in spirit to the present version, but may differ in detail to 568 | address new problems or concerns. 569 | 570 | Each version is given a distinguishing version number. If the 571 | Program specifies that a certain numbered version of the GNU General 572 | Public License "or any later version" applies to it, you have the 573 | option of following the terms and conditions either of that numbered 574 | version or of any later version published by the Free Software 575 | Foundation. If the Program does not specify a version number of the 576 | GNU General Public License, you may choose any version ever published 577 | by the Free Software Foundation. 578 | 579 | If the Program specifies that a proxy can decide which future 580 | versions of the GNU General Public License can be used, that proxy's 581 | public statement of acceptance of a version permanently authorizes you 582 | to choose that version for the Program. 583 | 584 | Later license versions may give you additional or different 585 | permissions. However, no additional obligations are imposed on any 586 | author or copyright holder as a result of your choosing to follow a 587 | later version. 588 | 589 | 15. Disclaimer of Warranty. 590 | 591 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 592 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 596 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 597 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 599 | 600 | 16. Limitation of Liability. 601 | 602 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 610 | SUCH DAMAGES. 611 | 612 | 17. Interpretation of Sections 15 and 16. 613 | 614 | If the disclaimer of warranty and limitation of liability provided 615 | above cannot be given local legal effect according to their terms, 616 | reviewing courts shall apply local law that most closely approximates 617 | an absolute waiver of all civil liability in connection with the 618 | Program, unless a warranty or assumption of liability accompanies a 619 | copy of the Program in return for a fee. 620 | 621 | END OF TERMS AND CONDITIONS 622 | 623 | How to Apply These Terms to Your New Programs 624 | 625 | If you develop a new program, and you want it to be of the greatest 626 | possible use to the public, the best way to achieve this is to make it 627 | free software which everyone can redistribute and change under these terms. 628 | 629 | To do so, attach the following notices to the program. It is safest 630 | to attach them to the start of each source file to most effectively 631 | state the exclusion of warranty; and each file should have at least 632 | the "copyright" line and a pointer to where the full notice is found. 633 | 634 | 635 | Copyright (C) 636 | 637 | This program is free software: you can redistribute it and/or modify 638 | it under the terms of the GNU General Public License as published by 639 | the Free Software Foundation, either version 3 of the License, or 640 | (at your option) any later version. 641 | 642 | This program is distributed in the hope that it will be useful, 643 | but WITHOUT ANY WARRANTY; without even the implied warranty of 644 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 645 | GNU General Public License for more details. 646 | 647 | You should have received a copy of the GNU General Public License 648 | along with this program. If not, see . 649 | 650 | Also add information on how to contact you by electronic and paper mail. 651 | 652 | If the program does terminal interaction, make it output a short 653 | notice like this when it starts in an interactive mode: 654 | 655 | Copyright (C) 656 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 657 | This is free software, and you are welcome to redistribute it 658 | under certain conditions; type `show c' for details. 659 | 660 | The hypothetical commands `show w' and `show c' should show the appropriate 661 | parts of the General Public License. Of course, your program's commands 662 | might be different; for a GUI interface, you would use an "about box". 663 | 664 | You should also get your employer (if you work as a programmer) or school, 665 | if any, to sign a "copyright disclaimer" for the program, if necessary. 666 | For more information on this, and how to apply and follow the GNU GPL, see 667 | . 668 | 669 | The GNU General Public License does not permit incorporating your program 670 | into proprietary programs. If your program is a subroutine library, you 671 | may consider it more useful to permit linking proprietary applications with 672 | the library. If this is what you want to do, use the GNU Lesser General 673 | Public License instead of this License. But first, please read 674 | . 675 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # dns_deep_state 2 | 3 | Find all secrets about DNS governing a domain 4 | 5 | Setting up a domain name for proper hosting of a web site, emails or other 6 | services can be quite counter-intuitive to people who are not familiar with how 7 | this system all works. 8 | 9 | Verifying that everything's been configured properly requires knowledge of many 10 | tools and the nature of interactions between different systems. 11 | 12 | This library aims to make it easier to run diagnostics and find where the 13 | secret cabal that causes DNS malfunction is hiding. 14 | 15 | ## This project is still not solidified into something that can be documented 16 | 17 | The internal and external interfaces are still in the process of being 18 | designed. I'm slowly placing the design elements as things go since I didn't 19 | have a great idea how to architect things from the start. 20 | 21 | As soon as things start to make more sense, this file will get updated with 22 | documentation on how to use the library and the CLI tool. 23 | 24 | ## Intentions 25 | 26 | This project is a rewrite of a script I wrote for work and that had really poor 27 | code quality. 28 | 29 | The intention of this project is to avoid having to teach how to use the 30 | multitude of tools for diagnosing a domain name's setup when helping out folks 31 | with web/email hosting. All the information should be available in one place. 32 | There's always at least one detail that slips by unnoticed when you need to use 33 | 4 or 5 different things. 34 | 35 | The library aspect of this project will produce a JSON data structure that 36 | contains information about the requested domain name, but also hints at things 37 | that might be misconfigured. 38 | 39 | The CLI should consume the JSON report and present the information in a 40 | human-friendly way. 41 | 42 | There might be more than one report in the future, but the first one that's 43 | planned should contain information about domain registration (RDAP/whois), DNS 44 | servers, Email DNS entries, and possible overrides in your local hosts 45 | database. 46 | 47 | With this information, it becomes easier to go from a question of the form "I'm 48 | not getting any email and my website is not responding!" to "oh! your domain is 49 | actually expired. is it possible that you forgot to pay for renewal? Your 50 | domain is registered with XYZ" 51 | 52 | It should help with weirder situations like "ah.. one of the DNS servers is 53 | responding with a different zone serial number. that explains why your problem 54 | is intermittent." 55 | 56 | Once this first report is done, there can be more information added like 57 | DNSSEC, CAA and other dns records of interest. 58 | 59 | There should at some point also be some way to feed a list of "recognized 60 | hosts" so that the CLI could identify where things are pointing to and whether 61 | or not that's a problem in your context. e.g. "your website is pointing 62 | directly to one of the web servers but it should really use the load balancer's 63 | IP address." 64 | 65 | stay tuned.. 66 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = [ 3 | "setuptools>=42", 4 | "wheel" 5 | ] 6 | build-backend = "setuptools.build_meta" 7 | -------------------------------------------------------------------------------- /renovate.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://docs.renovatebot.com/renovate-schema.json", 3 | "extends": [ 4 | "config:base", 5 | ":disableDependencyDashboard" 6 | ] 7 | } 8 | -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [metadata] 2 | name = dns_deep_state 3 | version = 0.0.1 4 | author = Gabriel Filion 5 | author_email = gabster@lelutin.ca 6 | description = Find all secrets about DNS governing a domain 7 | long_description = file: README.md 8 | long_description_content_type = text/markdown 9 | license = GPLv3 10 | license_files = LICENSE 11 | url = https://github.com/lelutin/dns_deep_state 12 | project_urls = 13 | Bug Tracker = https://github.com/lelutin/dns_deep_state/issues 14 | classifiers = 15 | Development Status :: 2 - Pre-Alpha 16 | Programming Language :: Python :: 3 17 | Programming Language :: Python :: 3.7 18 | Programming Language :: Python :: 3.8 19 | Programming Language :: Python :: 3.9 20 | License :: OSI Approved :: GNU General Public License v3 (GPLv3) 21 | Operating System :: OS Independent 22 | Topic :: Internet :: Name Service (DNS) 23 | Topic :: System :: Systems Administration 24 | Topic :: Utilities 25 | Environment :: Console 26 | Intended Audience :: Customer Service 27 | Intended Audience :: System Administrators 28 | Intended Audience :: Information Technology 29 | 30 | [options] 31 | package_dir = 32 | = src 33 | packages = find: 34 | python_requires = >=3.7 35 | install_requires = 36 | dnspython 37 | publicsuffix2 38 | whoisit>=2.2.0 39 | 40 | [options.packages.find] 41 | where = src 42 | 43 | [options.extras_require] 44 | test = 45 | pytest 46 | pytest-mock 47 | pytest-cov 48 | lint = 49 | flake8 50 | flake8-builtins 51 | flake8-type-checking 52 | flake8-rst-docparams 53 | flake8-comprehensions 54 | flake8-sfs 55 | pep8-naming 56 | types = 57 | mypy 58 | 59 | [flake8] 60 | select = E,F,W,C90,C40,TC,TC1,DP,SFS 61 | # We want to use only f-strings in this project 62 | extend-ignore = SFS301 63 | per-file-ignores = 64 | tests/*:DP 65 | max-complexity = 10 66 | # The GitHub editor is 127 chars wide 67 | max-line-length = 127 68 | 69 | [tool:pytest] 70 | addopts = --cov=dns_deep_state 71 | markers = 72 | integration: Tests that run real queries against rdap, whois and dns (deselect with '-m "not integration"') 73 | 74 | [mypy] 75 | ignore_missing_imports = True 76 | 77 | [coverage:run] 78 | branch = True 79 | 80 | [coverage:report] 81 | fail_under = 90 82 | show_missing = True 83 | skip_empty = True 84 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | import setuptools 2 | 3 | setuptools.setup() 4 | -------------------------------------------------------------------------------- /src/dns_deep_state/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lelutin/dns_deep_state/68cc0d85d90931f823eae74cdf4151869d83c486/src/dns_deep_state/__init__.py -------------------------------------------------------------------------------- /src/dns_deep_state/dns.py: -------------------------------------------------------------------------------- 1 | """Query the DNS about some aspects of a domain.""" 2 | from __future__ import annotations 3 | 4 | from typing import TYPE_CHECKING 5 | 6 | import socket 7 | import dns.exception 8 | import dns.resolver 9 | 10 | from dns_deep_state.exceptions import DnsQueryError, DomainError 11 | 12 | if TYPE_CHECKING: 13 | from typing import Optional, Set, List, Dict # pragma: no cover 14 | 15 | 16 | class DnsProbe: 17 | """Starting with an FQDN, inspect DNS state and consistency of configuration. 18 | 19 | In order to have properly functional services, many details in the DNS need 20 | to be setup properly. Furthermore, some details that are optional help 21 | with different aspects of verfications and validation by third parties, so 22 | we need to take a look at those too. 23 | 24 | .. note:: DNS depends on the domain registration to be in order, so 25 | Registry checks should happen before we can reach this aspect of the 26 | infrastructure. 27 | """ 28 | 29 | # This is the AAAA from a.iana-servers.net. 30 | KNOWN_IPV6_IP = "2001:500:8f::53" 31 | 32 | def __init__(self) -> None: 33 | """Prepare DNS resolver.""" 34 | self.res = dns.resolver.Resolver() 35 | 36 | # Without setting this up, queries that don't turn up a result will get 37 | # stuck for the default timeout of 30 seconds. On the contrary, setting 38 | # those too low, like 1, can result in useless timeout errors when 39 | # certain DNS servers take too long to respond. 40 | self.res.timeout = 3 # type: ignore 41 | self.res.lifetime = 3 # type: ignore 42 | 43 | self.ipv6_enabled = self._ipv6_connectivity() 44 | 45 | self._saved_name_servers: Optional[List[str]] = None 46 | 47 | def _ipv6_connectivity(self) -> bool: 48 | """Try to connect to a known IPv6 address to test connectivity. 49 | 50 | :return: True if ipv6 connectivity is possible. 51 | """ 52 | ipv6_supported = False 53 | if socket.has_ipv6: 54 | s = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM) 55 | try: 56 | s.connect((self.KNOWN_IPV6_IP, 53)) 57 | ipv6_supported = True 58 | except OSError: 59 | pass 60 | finally: 61 | s.close() 62 | 63 | return ipv6_supported 64 | 65 | def canonical_name(self, hostname: str) -> Optional[str]: 66 | """Given that hostname is a CNAME, resolve its canonical name. 67 | 68 | :param hostname: Hostname for which we're searching a canonical name. 69 | 70 | :return: a string containing the canonical name if found. Otherwise, 71 | return `None`. 72 | 73 | :raises: See :meth:`lookup`. `NoAnswer` is not raised though. 74 | 75 | .. note:: 76 | 77 | If you care about the presence of a CNAME for a hostname, it is 78 | best to resolve the canonical name first. Looking up the A record 79 | for a hostname that has a CNAME will automatically be dereferenced 80 | so it won't tell you if there was a CNAME in the way to getting the 81 | IP address. 82 | """ 83 | try: 84 | ans = self.lookup(hostname, "CNAME") 85 | response = ans.canonical_name # type: ignore 86 | except dns.resolver.NoAnswer: 87 | # This response from DNS servers means that hostname does not have 88 | # a CNAME RR, which is not per se an error. 89 | # It's possible with this response that the subdomain doesn't exist 90 | # at all. The only way to verify this is by querying for other RR 91 | # types for the same subdomain. 92 | response = None 93 | 94 | return response 95 | 96 | def name_servers(self, hostname: str) -> Set[str]: 97 | """Get all NS entries for hostname. 98 | 99 | This will only return the hostname strings. If you want to then send a 100 | query directly to one of the nameservers, don't forget that you'll need 101 | to resolve the hosts to IP addresses. 102 | 103 | :param hostname: Hostname used in query for NS type record. 104 | 105 | :return: A set of strings for all found nameservers. 106 | """ 107 | ans = self.lookup(hostname, "NS") 108 | response = ans.rrset # type: ignore 109 | return {x.to_text() for x in response} 110 | 111 | def soa(self, hostname: str, name_server_ip: str) -> Dict[str, str]: 112 | """Get a domain's SOA record. 113 | 114 | For the purposes of this library, when we're requesting an SOA record, 115 | we want to get it from one specific nameserver. This is because we want 116 | to check that all servers respond with the same information. 117 | 118 | :param hostname: The domain name for which we're looking up the SOA 119 | record. 120 | 121 | :param name_server_ip: IP address of the DNS server we're probing for the 122 | SOA record. The dnspython library is not able to query directly to 123 | a hostname, so this value needs to be an IP address (v4 or v6). 124 | 125 | :return: A dictionary containing all information from the SOA record. 126 | """ 127 | ans = self.lookup(hostname, "SOA", server_ip=name_server_ip) 128 | response = ans.rrset[0] # type: ignore 129 | # Unpack to hide library details from callers 130 | res = { 131 | "mname": response.mname.to_text(), 132 | "rname": response.rname.to_text(), 133 | "serial": response.serial, 134 | "refresh": response.refresh, 135 | "retry": response.retry, 136 | "expire": response.expire, 137 | "ttl": response.minimum, 138 | } 139 | 140 | return res 141 | 142 | def v4_address(self, hostname: str) -> List[str]: 143 | """Get A record for hostname. 144 | 145 | :param hostname: The hostname that we'll lookup for. 146 | 147 | :return: A list of addresses that were found for the A record. If 148 | nothing is found, the list is empty. 149 | """ 150 | ans = self.lookup(hostname, "A") 151 | response = ans.rrset # type: ignore 152 | 153 | return [x.to_text() for x in response] 154 | 155 | def v6_address(self, hostname: str) -> List[str]: 156 | """Get AAAA record for hostname. 157 | 158 | :param hostname: The hostname that we,ll lookup for. 159 | 160 | :return: A list of addresses that were found for the AAAA record. If 161 | nothing is found, the list is empty. 162 | """ 163 | ans = self.lookup(hostname, "AAAA") 164 | response = ans.rrset # type: ignore 165 | 166 | return [x.to_text() for x in response] 167 | 168 | def lookup(self, hostname: str, lookup_type: str, 169 | server_ip: Optional[str] = None) -> dns.resolver.Answer: 170 | """Grab DNS RR of type `lookup_type` for `hostname`. 171 | 172 | :param hostname: The hostname for which we're requesting information 173 | from the DNS. 174 | :param lookup_type: The type of DNS record that we're requesting. 175 | :param server_ip: Optional IP address of the DNS server we're sending 176 | our request towards. This can be used to verify that specific 177 | servers are responding appropriately. 178 | 179 | :return: whatever response object we got from the dnspython library. 180 | Wrappers to this method should handle those response objects 181 | accordingly and hide the library details from their own responses 182 | by reformatting. This'll make sure that only a limited number of 183 | methods in this class handle implementation details with regards to 184 | how DNS entries are looked up. 185 | 186 | :raises dns_deep_state.exceptions.DomainError: received NXDOMAIN, 187 | meaning that the domain name might not be registered, or the dns 188 | library can't find NS servers 189 | :raises dns_deep_state.exceptions.DnsQueryError: recieved YXDOMAIN, 190 | meaning that the query was malformed (too long), or the query timed 191 | out 192 | :raises dns.resolver.NoAnswer: in order for wrapper methods to handle 193 | this case. 194 | """ 195 | if server_ip is not None: 196 | self._set_nameservers([server_ip]) 197 | 198 | try: 199 | response = self.res.resolve(hostname, lookup_type) 200 | except dns.resolver.NXDOMAIN as err: 201 | self._reset_nameservers() 202 | # In the case of CNAME queries, we'll get NXDOMAIN if the domain 203 | # name is not registered at all. In those cases, there's not much 204 | # use asking further questions to DNS. 205 | raise DomainError(err) 206 | except dns.resolver.NoNameservers as err: 207 | self._reset_nameservers() 208 | # Got SERVFAIL, nothing else will resolve for this domain 209 | raise DomainError(err) 210 | except dns.resolver.YXDOMAIN as err: 211 | self._reset_nameservers() 212 | raise DnsQueryError(err) 213 | except dns.exception.Timeout as err: 214 | self._reset_nameservers() 215 | raise DnsQueryError(err) 216 | 217 | self._reset_nameservers() 218 | return response 219 | 220 | def _set_nameservers(self, name_servers: List[str]) -> None: 221 | """Change the nameservers that'll get queried for DNS. 222 | 223 | :param name_servers: List of IP addresses of name servers. 224 | """ 225 | self._saved_name_servers = self.res.nameservers 226 | self.res.nameservers = name_servers 227 | 228 | def _reset_nameservers(self) -> None: 229 | """Set nameservers back to what was previously known, if anything.""" 230 | if self._saved_name_servers is not None: 231 | self.res.nameservers = self._saved_name_servers 232 | -------------------------------------------------------------------------------- /src/dns_deep_state/exceptions.py: -------------------------------------------------------------------------------- 1 | """Exceptions used by the dns_state library.""" 2 | 3 | 4 | class DomainError(Exception): 5 | """The domain name does not exist or cannot be probed.""" 6 | 7 | 8 | class DnsQueryError(Exception): 9 | """The DNS query failed.""" 10 | -------------------------------------------------------------------------------- /src/dns_deep_state/hosts.py: -------------------------------------------------------------------------------- 1 | """Perform some verifications on the local hosts database.""" 2 | import re 3 | 4 | 5 | class HostsProbe: 6 | """Test for presence of a hostname inside the local hosts file. 7 | 8 | The presence of a hostname inside this file might drastically change the 9 | behavior of a service that you're trying to use on a certain hostname, so 10 | it's important to check whether you have such an override in place. 11 | 12 | :method: in_database() 13 | 14 | :param database_path: Absolute path to the local hosts database file. 15 | """ 16 | 17 | def __init__(self, database_path: str = "/etc/hosts") -> None: 18 | """Prepare all relevant drivers for queries.""" 19 | self.database_path = database_path 20 | 21 | self._hosts_cache = [] 22 | with open(self.database_path, 'r') as hosts: 23 | for line in hosts.readlines(): 24 | self._hosts_cache.append(line) 25 | 26 | def in_database(self, hostname: str) -> bool: 27 | """Check whether a hostname is present in the local hosts database. 28 | 29 | :param hostname: A hostname that we'll lookup in the hosts database. 30 | 31 | :return: True if hostname is in hosts database, False otherwise. 32 | """ 33 | for line in self._hosts_cache: 34 | # remove trailing newline char 35 | line = re.sub(r'\n$', '', line) 36 | # chop off comments 37 | line = re.sub(r' *#.*$', '', line) 38 | # empty up lines that have only spaces or tabs; they're not 39 | # interesting to process 40 | line = re.sub(r'^[ \t]+$', '', line) 41 | # discard empty lines 42 | if not line: 43 | continue 44 | 45 | host_aliases = line.split()[1:] 46 | 47 | if hostname in host_aliases: 48 | return True 49 | 50 | return False 51 | -------------------------------------------------------------------------------- /src/dns_deep_state/registry.py: -------------------------------------------------------------------------------- 1 | """Query domain registries about a domain name.""" 2 | import whoisit 3 | import whoisit.errors 4 | 5 | from dns_deep_state.exceptions import DomainError 6 | 7 | 8 | class RegistryProbe: 9 | """Find out how a domain is registered and its status. 10 | 11 | This is the starting point whenever inspecting a domain. If it's not 12 | registered, there isn't much point in doing any further inspection. But the 13 | registry has more interesting information like the domain's current status 14 | and the namesevers known to the registry. 15 | 16 | We will be querying RDAP about the requested domain since it's the system 17 | that's bound to replace whois. However, there are still many TLDs that have 18 | not implemented RDAP yet, so we might need to query whois for those and 19 | we'll want to somehow determine which ones we need to fallback to doing 20 | this for. 21 | """ 22 | 23 | def __init__(self) -> None: 24 | """Initialize the registry querying libraries.""" 25 | self.rdap_bootstrap_info = whoisit.bootstrap() 26 | 27 | def domain_name(self, fqdn: str) -> dict: 28 | """Get information about domain `fqdn` from registry database. 29 | 30 | :param fqdn: The fully qualified domain name that we're querying 31 | information for. 32 | 33 | :return: A dictionary containing registration information. 34 | """ 35 | try: 36 | domain = whoisit.domain(fqdn) 37 | except whoisit.errors.ResourceDoesNotExist: 38 | raise DomainError(f"Domain {fqdn} is not registered.") 39 | except whoisit.errors.QueryError as e: 40 | if any("DH_KEY_TOO_SMALL" in s for s in e.args): 41 | # Let's retry with weak ssl permitted 42 | domain = whoisit.domain(fqdn, allow_insecure_ssl=True) 43 | else: 44 | raise 45 | 46 | return domain 47 | -------------------------------------------------------------------------------- /src/dns_deep_state/report.py: -------------------------------------------------------------------------------- 1 | """Gather information about a domain name and produce a report about it. 2 | 3 | Rough early specs: 4 | 5 | Output of the report should be in JSON. 6 | 7 | Input should be a domain name (maybe some additional sub-domains?) 8 | 9 | There should be a binary that uses the library and formats the report to 10 | screen 11 | 12 | There should be some configuration format that lets you mark whether 13 | reported hosts are known to be something and whether it's problematic to 14 | the user or not. maybe only for the binary? It should be possible for users 15 | to specify an alternative configuration file. 16 | 17 | """ 18 | from __future__ import annotations 19 | 20 | import json 21 | from typing import TYPE_CHECKING 22 | 23 | from dns.resolver import NoAnswer 24 | from publicsuffix2 import PublicSuffixList 25 | 26 | from dns_deep_state.dns import DnsProbe 27 | from dns_deep_state.hosts import HostsProbe 28 | from dns_deep_state.registry import RegistryProbe 29 | from dns_deep_state.exceptions import DomainError 30 | 31 | if TYPE_CHECKING: 32 | from typing import Set, Dict, Union # pragma: no cover 33 | 34 | 35 | class DomainReport: 36 | """Inspect the state of a domain name and report on possible issues.""" 37 | 38 | def __init__(self) -> None: 39 | """Initialise information probes.""" 40 | self.psl = PublicSuffixList() 41 | self.reg = RegistryProbe() 42 | self.dns = DnsProbe() 43 | self.hosts = HostsProbe() 44 | 45 | def full_report(self, fqdn: str) -> str: 46 | """Grab information about `fqdn` and produce a report about it. 47 | 48 | :param fqdn: The fully qualified domain name for which a report is 49 | produced. 50 | 51 | :raises ValueError: If `fqdn` is not using a known public suffix. 52 | Indeed, we'll be prodding some public services for information 53 | about the domain, so it doesn't make much sense to run the 54 | information gathering for a domain name that won't have any valid 55 | information on those services. 56 | 57 | :return: a JSON-serialized data structure 58 | 59 | .. note:: 60 | If `fqdn` is not a second-level domain (e.g. the name that would be 61 | registered with a registry, the report will be run on the 62 | second-level domain part of it instead. 63 | 64 | This method inspects data returned from all probes and also 65 | adds errors for the following correlations: 66 | the domain name uses one of the known public suffixes 67 | if not, fail early 68 | the DNS servers in the zone match the ones in the registry 69 | check reported resolved hosts for presence in local hosts database 70 | """ 71 | # TODO decide exactly what structure the report should take 72 | report = {} 73 | 74 | domain_name = self.psl.get_sld(fqdn, strict=True) 75 | if domain_name is None: 76 | raise ValueError( 77 | f"{fqdn} is not using a known public suffix or TLD") 78 | report["domain"] = domain_name 79 | 80 | report["registry"] = self.registry_report(fqdn) 81 | report["dns"] = self.dns_report(fqdn) 82 | # TODO extract portion of report with resolved hosts and give that to 83 | # the next report method instead of fqdn 84 | hostnames: Set[str] = set() 85 | report["hosts"] = self.local_hosts_report(hostnames) 86 | 87 | return json.dumps(report) 88 | 89 | def registry_report(self, domain_name: str) -> dict: 90 | """Run a full inspection and produce a report about what was found. 91 | 92 | The registry should be checked for: 93 | domain is registered 94 | not expired 95 | not in a problematic status 96 | the DNS hosts in the registry have glue records 97 | 98 | :param domain_name: The domain name for which we'll be gathering 99 | information into a report. 100 | 101 | :return: A dictionary containing report information. 102 | """ 103 | info = self.reg.domain_name(domain_name) 104 | report = {} 105 | report["status"] = info["status"] 106 | report["expiration_date"] = str(info["expiration_date"]) 107 | report["registrar"] = info["entities"]["registrar"][0]["name"] 108 | report["nameservers"] = info["nameservers"] 109 | return report 110 | 111 | def dns_report(self, fqdn: str) -> dict: 112 | """Run all DNS inspections and produce report as a dictionary. 113 | 114 | To produce a full report we want to inspect the following details about 115 | a domain name: 116 | * List out NS entries 117 | * Grab the SOA and report the serial 118 | * Get the SOA from all NS entries and compare the serials. If 119 | there is a mismatch, add an error in the report about a 120 | mismatch in the SOA and which nameservers disagree 121 | * If any of the NS servers fail to respond, add an error about 122 | each one that failed 123 | * If no NS server responded, raise an exception to fail early 124 | * Details about email setup 125 | * MX is present. all values have a PTR corresponding to the same 126 | hostname 127 | * check all hosts in the same way as resolving tests down below 128 | and add results to report 129 | * SPF is present 130 | * DKIM is present (we'll need a configuration option for a set of 131 | DKIM sub-domains to search for) 132 | * DMARC is present 133 | * MTA-STS is present 134 | * onionmx SRV field exists 135 | * SRV records exist for IMAP/POP3 136 | * autodiscover/autoconfig TXT entries exist 137 | * general security fields 138 | * DNSSEC: DS and DNSKEY 139 | * CAA 140 | * Resolve a series of hosts 141 | * check for CNAME first and report if any is found 142 | * A and AAAA, also check for PTR on found values 143 | * always check if there are NS entries for subdomains and report 144 | the delegations that were found 145 | * at least: 146 | * NS servers 147 | * top of domain 148 | * www subdomain 149 | * hosts found in SRV records 150 | * it would be a good idea to have a parameter for extra hosts to 151 | include in the report 152 | 153 | :param fqdn: The domain name for which we'll gather DNS information 154 | into a report. 155 | 156 | :return: A dictionary containing report information. 157 | """ 158 | report = {} 159 | 160 | try: 161 | nameservers = self.dns.name_servers(fqdn) 162 | except (DomainError, NoAnswer): 163 | raise DomainError( 164 | f"No nameserver was found for {fqdn}. Cannot go further.") 165 | 166 | ns_data = [] 167 | for ns in nameservers: 168 | ns_ips = self.dns.v4_address(ns) 169 | if self.dns.ipv6_enabled: 170 | ns_ips.extend(self.dns.v6_address(ns)) 171 | 172 | for ns_ip in ns_ips: 173 | ns_struct: Dict[str, Union[str, Dict[str, str]]] = { 174 | "hostname": ns, 175 | "ip_address": ns_ip, 176 | } 177 | # TODO catch errors from this 178 | soa = self.dns.soa(fqdn, ns_ip) 179 | 180 | ns_struct["soa"] = soa 181 | 182 | ns_data.append(ns_struct) 183 | 184 | report["nameservers"] = ns_data 185 | 186 | return report 187 | 188 | def local_hosts_report(self, hosts: Set[str]) -> dict: 189 | """Produce a report about the presence of hosts in the local database. 190 | 191 | Host names will not be verified for validity, only whether or not they 192 | are in the local hosts database. 193 | 194 | :param hosts: Set of unique host names 195 | 196 | :return: A dictionary with host names as keys and a boolean as values 197 | to indicate if the corresponding host name was found in the local 198 | database. 199 | """ 200 | report = {} 201 | for h in hosts: 202 | report[h] = self.hosts.in_database(h) 203 | return report 204 | -------------------------------------------------------------------------------- /tests/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lelutin/dns_deep_state/68cc0d85d90931f823eae74cdf4151869d83c486/tests/__init__.py -------------------------------------------------------------------------------- /tests/integration/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lelutin/dns_deep_state/68cc0d85d90931f823eae74cdf4151869d83c486/tests/integration/__init__.py -------------------------------------------------------------------------------- /tests/integration/test_all_fine.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/python3 2 | """Make a live run with the library with a domain that's working nicely. 3 | 4 | Hopefully we can get information from all systems as part of the report for 5 | this test. 6 | """ 7 | import pytest 8 | 9 | from dns_deep_state.report import DomainReport 10 | 11 | 12 | @pytest.mark.integration 13 | def test_live_full_report(): 14 | """Get information from example.com from live systems.""" 15 | dr = DomainReport() 16 | 17 | report = dr.full_report("example.com") 18 | 19 | # Nothing super useful to check for now (but there will be once the 20 | # structure of the report starts solidifying). 21 | # The instructions above at least test that we're not getting unexpected 22 | # errrors while running, and we can see what the report looks like: 23 | print(report) 24 | 25 | 26 | if __name__ == '__main__': 27 | test_live_full_report() 28 | -------------------------------------------------------------------------------- /tests/integration/test_invalid_domain.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/python3 2 | """Try to resolve a domain that does not resolve. 3 | 4 | We'll expect a certain exception in this case. 5 | """ 6 | import pytest 7 | 8 | from dns_deep_state.report import DomainReport 9 | from dns_deep_state.exceptions import DomainError 10 | 11 | 12 | @pytest.mark.integration 13 | def test_domain_unknown_tld(): 14 | """Get report for domain with unknown TLD.""" 15 | dr = DomainReport() 16 | 17 | with pytest.raises(ValueError): 18 | dr.full_report("something.invalid") 19 | 20 | 21 | @pytest.mark.integration 22 | def test_domain_no_resolve(): 23 | """Get information from domain that is guaranteed not to resolve.""" 24 | dr = DomainReport() 25 | 26 | with pytest.raises(DomainError): 27 | dr.full_report("hopefullythisdomainwillneverexist.com") 28 | -------------------------------------------------------------------------------- /tests/test_dns.py: -------------------------------------------------------------------------------- 1 | """Test DNS verification routines.""" 2 | import pytest 3 | 4 | from dns_deep_state import dns 5 | from dns_deep_state.exceptions import DomainError, DnsQueryError 6 | 7 | from dns.resolver import NoAnswer, NXDOMAIN, YXDOMAIN, NoNameservers 8 | from dns.exception import Timeout 9 | 10 | 11 | def test__ipv6_conectivity(mocker): 12 | """IPv6 connectivity is possible.""" 13 | m = mocker.patch('socket.socket.connect', mocker.Mock()) 14 | resolver = dns.DnsProbe() 15 | 16 | m.assert_called_once() 17 | 18 | assert resolver.ipv6_enabled is True 19 | 20 | 21 | def test__socket_no_ipv6(mocker): 22 | """The socket module does not have IPv6 capabilities.""" 23 | mocker.patch('socket.has_ipv6', False) 24 | resolver = dns.DnsProbe() 25 | 26 | assert resolver.ipv6_enabled is False 27 | 28 | 29 | def test__failed_ipv6_conectivity(mocker): 30 | """IPv6 connectivity is not possible.""" 31 | m = mocker.patch('socket.socket.connect', mocker.Mock(side_effect=OSError)) 32 | resolver = dns.DnsProbe() 33 | 34 | m.assert_called_once() 35 | 36 | assert resolver.ipv6_enabled is False 37 | 38 | 39 | def test_canonical_name(mocker): 40 | """Request CNAME for a hostname.""" 41 | mocker.patch('dns_deep_state.dns.DnsProbe._ipv6_connectivity', 42 | mocker.Mock(return_value=True)) 43 | resolver = dns.DnsProbe() 44 | stub_lookup = mocker.Mock( 45 | return_value=mocker.Mock(canonical_name="c.domain.tld")) 46 | mocker.patch("dns_deep_state.dns.DnsProbe.lookup", stub_lookup) 47 | canon = resolver.canonical_name("sub.domain.tld") 48 | 49 | stub_lookup.assert_called_once_with("sub.domain.tld", "CNAME") 50 | assert canon == "c.domain.tld" 51 | 52 | 53 | def test_canonical_name_not_found(mocker): 54 | """No result found for requested CNAME.""" 55 | mocker.patch('dns_deep_state.dns.DnsProbe._ipv6_connectivity', 56 | mocker.Mock(return_value=True)) 57 | resolver = dns.DnsProbe() 58 | stub_lookup = mocker.Mock(side_effect=NoAnswer) 59 | mocker.patch("dns_deep_state.dns.DnsProbe.lookup", stub_lookup) 60 | canon = resolver.canonical_name("nope.domain.tld") 61 | 62 | stub_lookup.assert_called_once_with("nope.domain.tld", "CNAME") 63 | assert canon is None 64 | 65 | 66 | def test_name_servers(mocker): 67 | """Request NS for a hostname.""" 68 | name_servers = {"ns1.domain.tld", "ns2.domain.tld", "ns3.domain.tld"} 69 | name_server_texts = mocker.Mock(side_effect=name_servers) 70 | mock_rrset = [ 71 | mocker.Mock(to_text=name_server_texts), 72 | mocker.Mock(to_text=name_server_texts), 73 | mocker.Mock(to_text=name_server_texts)] 74 | stub_lookup = mocker.Mock(return_value=mocker.Mock(rrset=mock_rrset)) 75 | mocker.patch("dns_deep_state.dns.DnsProbe.lookup", stub_lookup) 76 | mocker.patch('dns_deep_state.dns.DnsProbe._ipv6_connectivity', 77 | mocker.Mock(return_value=True)) 78 | resolver = dns.DnsProbe() 79 | ns = resolver.name_servers("domain.tld") 80 | 81 | stub_lookup.assert_called_once_with("domain.tld", "NS") 82 | assert ns == name_servers 83 | 84 | 85 | def test_soa(mocker): 86 | """Request SOA for a hostname from a specific nameserver.""" 87 | expected = { 88 | "mname": "ns1.example.com", 89 | "rname": "hostmaster.example.com", 90 | "serial": "1630021470", 91 | "refresh": "86400", 92 | "retry": "7200", 93 | "expire": "4000000", 94 | "ttl": "11200", 95 | } 96 | 97 | lib_rr_params = { 98 | "mname": mocker.Mock( 99 | to_text=mocker.Mock(return_value=expected["mname"])), 100 | "rname": mocker.Mock( 101 | to_text=mocker.Mock(return_value=expected["rname"])), 102 | "serial": expected["serial"], 103 | "refresh": expected["refresh"], 104 | "retry": expected["retry"], 105 | "expire": expected["expire"], 106 | "minimum": expected["ttl"], 107 | } 108 | mock_rr = mocker.Mock(**lib_rr_params) 109 | mock_answer = mocker.Mock(rrset=[mock_rr]) 110 | stub_lookup = mocker.Mock(return_value=mock_answer) 111 | mocker.patch("dns_deep_state.dns.DnsProbe.lookup", stub_lookup) 112 | 113 | mocker.patch('dns_deep_state.dns.DnsProbe._ipv6_connectivity', 114 | mocker.Mock(return_value=True)) 115 | resolver = dns.DnsProbe() 116 | soa = resolver.soa("example.com", "127.1.2.3") 117 | 118 | stub_lookup.assert_called_once_with("example.com", "SOA", server_ip="127.1.2.3") 119 | assert soa == expected 120 | 121 | 122 | @pytest.mark.parametrize("ip_address,rr_type,method_name", 123 | [("127.0.0.98", "A", "v4_address"), 124 | ("fe80::98", "AAAA", "v6_address")]) 125 | def test_v46_address(mocker, ip_address, rr_type, method_name): 126 | """Successfully get the IPv4 or IPv6 address of a hostname.""" 127 | mock_rr = mocker.Mock(to_text=mocker.Mock(return_value=ip_address)) 128 | mock_answer = mocker.Mock(rrset=[mock_rr]) 129 | stub_lookup = mocker.Mock(return_value=mock_answer) 130 | mocker.patch("dns_deep_state.dns.DnsProbe.lookup", stub_lookup) 131 | 132 | mocker.patch('dns_deep_state.dns.DnsProbe._ipv6_connectivity', 133 | mocker.Mock(return_value=True)) 134 | resolver = dns.DnsProbe() 135 | lookup_method = getattr(resolver, method_name) 136 | resd_addr = lookup_method("domain.tld") 137 | 138 | stub_lookup.assert_called_once_with("domain.tld", rr_type) 139 | 140 | assert resd_addr == [ip_address] 141 | 142 | 143 | @pytest.mark.parametrize("raised_excpt,expected_excpt", 144 | [(NXDOMAIN, DomainError), 145 | (NoNameservers, DomainError), 146 | (YXDOMAIN, DnsQueryError), 147 | (Timeout, DnsQueryError)]) 148 | def test_lookup_server_error(mocker, raised_excpt, expected_excpt): 149 | """No result found or no nameserver.""" 150 | mocker.patch('dns_deep_state.dns.DnsProbe._ipv6_connectivity', 151 | mocker.Mock(return_value=True)) 152 | resolver = dns.DnsProbe() 153 | stub_resolve = mocker.Mock(side_effect=raised_excpt) 154 | mocker.patch("dns.resolver.Resolver.resolve", stub_resolve) 155 | with pytest.raises(expected_excpt): 156 | resolver.lookup("nope.domain.tld", "A") 157 | 158 | 159 | @pytest.mark.parametrize("ns_ip", [None, '127.1.2.3']) 160 | def test_lookup(mocker, ns_ip): 161 | """Run a DNS lookup of a certain type and get a response back.""" 162 | mocker.patch('dns_deep_state.dns.DnsProbe._ipv6_connectivity', 163 | mocker.Mock(return_value=True)) 164 | 165 | fake_response = mocker.Mock() 166 | stub_resolve = mocker.Mock(return_value=fake_response) 167 | mocker.patch("dns.resolver.Resolver.resolve", stub_resolve) 168 | 169 | resolver = dns.DnsProbe() 170 | default_name_servers = resolver.res.nameservers 171 | 172 | result = resolver.lookup('yep.domain.tld', 'A', ns_ip) 173 | 174 | # this may have been changed during the function call but in all cases it 175 | # should be set back to the original value once the lookup is finished. 176 | assert resolver.res.nameservers == default_name_servers 177 | # the actual value is not important, but as long as the return value is the 178 | # same thing as what gets returned by the actual dns lookup 179 | assert result == fake_response 180 | 181 | 182 | def test_set_nameservers(mocker): 183 | """Change the list of probed nameservers.""" 184 | mocker.patch('dns_deep_state.dns.DnsProbe._ipv6_connectivity', 185 | mocker.Mock(return_value=True)) 186 | resolver = dns.DnsProbe() 187 | resolver._set_nameservers(['1.2.3.4', '9.8.7.6']) 188 | 189 | assert resolver.res.nameservers == ['1.2.3.4', '9.8.7.6'] 190 | 191 | 192 | def test_reset_nameservers(mocker): 193 | """Put previously known nameservers back in place.""" 194 | mocker.patch('dns_deep_state.dns.DnsProbe._ipv6_connectivity', 195 | mocker.Mock(return_value=True)) 196 | resolver = dns.DnsProbe() 197 | resolver.res.nameservers = ['10.10.10.10', '10.20.30.40'] 198 | resolver._saved_name_servers = ['192.168.99.66'] 199 | 200 | resolver._reset_nameservers() 201 | 202 | assert resolver.res.nameservers == ['192.168.99.66'] 203 | 204 | 205 | def test_reset_nameservers_nothing_known(mocker): 206 | """Trying to reset nameservers but nothing previously known.""" 207 | mocker.patch('dns_deep_state.dns.DnsProbe._ipv6_connectivity', 208 | mocker.Mock(return_value=True)) 209 | resolver = dns.DnsProbe() 210 | resolver.res.nameservers = ['5.5.5.5', '42.42.42.42'] 211 | # This is the default, but we'll still just force the scenario in place. 212 | resolver._saved_name_servers = None 213 | 214 | resolver._reset_nameservers() 215 | 216 | assert resolver.res.nameservers == ['5.5.5.5', '42.42.42.42'] 217 | -------------------------------------------------------------------------------- /tests/test_hosts.py: -------------------------------------------------------------------------------- 1 | """Test features related to /etc/hosts.""" 2 | from dns_deep_state import hosts 3 | import pytest 4 | 5 | 6 | hosts_file = """127.0.0.1 localhost 7 | 8 | #192.168.10.10 nope ## this line should not match 9 | 192.168.10.12 remote remote.domain # this should still match 10 | 192.158.10.25 hostname.fqdn""" 11 | 12 | 13 | @pytest.mark.parametrize("hostname,result", 14 | [("hostname.fqdn", True), ("remote", True), 15 | ("rem", False), ("nope", False), 16 | ("192.158.10.25", False)]) 17 | def test_hostname_found(mocker, hostname, result): 18 | """We're searching for a hostname which is present in the database.""" 19 | m = mocker.patch('builtins.open', mocker.mock_open(read_data=hosts_file)) 20 | 21 | h = hosts.HostsProbe() 22 | present = h.in_database(hostname) 23 | 24 | m.assert_called_once_with("/etc/hosts", "r") 25 | assert present is result 26 | -------------------------------------------------------------------------------- /tests/test_registry.py: -------------------------------------------------------------------------------- 1 | """Test domain registry querying.""" 2 | import pytest 3 | 4 | from dns_deep_state.exceptions import DomainError 5 | from dns_deep_state.registry import RegistryProbe 6 | import whoisit.errors 7 | 8 | 9 | # It's not really necessary to have something so realistic, but it gives a 10 | # good idea of the expected format for the returned data structure. This is 11 | # directly the data structure returned by the whoisit library since it 12 | # makes a lot of sense. 13 | # 14 | # Note, however, that the ToS URL has been shortened and the registration 15 | # dates are strings instead of datetime objects. 16 | expected_rdap_info = { 17 | 'handle': '2336799_DOMAIN_COM-VRSN', 18 | 'parent_handle': '', 19 | 'name': 'EXAMPLE.COM', 20 | 'whois_server': '', 21 | 'type': 'domain', 22 | 'terms_of_service_url': 'https://www.verisign.com/domain-names/...', 23 | 'copyright_notice': '', 24 | 'description': [], 25 | 'last_changed_date': None, 26 | 'registration_date': "1995-8-14", 27 | 'expiration_date': "2021-8-13", 28 | 'url': 'https://rdap.verisign.com/com/v1/domain/EXAMPLE.COM', 29 | 'rir': '', 30 | 'entities': { 31 | 'registrar': [{ 32 | 'handle': '376', 33 | 'type': 'entity', 34 | 'name': 'RESERVED-Internet Assigned Numbers Authority'}]}, 35 | 'nameservers': ['A.IANA-SERVERS.NET', 'B.IANA-SERVERS.NET'], 36 | 'status': ['client delete prohibited', 37 | 'client transfer prohibited', 38 | 'client update prohibited']} 39 | 40 | 41 | def test_domain_info_from_rdap(mocker): 42 | """Request information about a domain and get it from RDAP.""" 43 | module_mock = mocker.MagicMock(bootstrap=mocker.Mock) 44 | mocker.patch("dns_deep_state.registry.whoisit", module_mock) 45 | reg = RegistryProbe() 46 | 47 | module_mock.domain = mocker.Mock(return_value=expected_rdap_info) 48 | 49 | info = reg.domain_name("example.com") 50 | 51 | assert info == expected_rdap_info 52 | 53 | 54 | def test_domain_info_unregistered(mocker): 55 | """Request information for a domain that is not currently registered.""" 56 | raised_exc = whoisit.errors.ResourceDoesNotExist 57 | module_mock = mocker.MagicMock( 58 | bootstrap=mocker.Mock, 59 | errors=whoisit.errors) 60 | mocker.patch("dns_deep_state.registry.whoisit", module_mock) 61 | reg = RegistryProbe() 62 | 63 | module_mock.domain = mocker.Mock(side_effect=raised_exc) 64 | with pytest.raises(DomainError): 65 | reg.domain_name("somethingnotthere.com") 66 | 67 | 68 | def test_domain_rdap_server_weak_ssl(mocker): 69 | """Replies from RDAP servers with too weak ssl should still function.""" 70 | raised_exc = whoisit.errors.QueryError( 71 | "Failed to make a GET request to " 72 | "https://rdap.nominet.uk/work/domain/nic.work: " 73 | "HTTPSConnectionPool(host='rdap.nominet.uk', port=443): Max retries " 74 | "exceeded with url: /work/domain/nic.work (Caused by " 75 | "SSLError(SSLError(1, '[SSL: DH_KEY_TOO_SMALL] dh key too small " 76 | "(_ssl.c:1123)')))") 77 | domain_method = mocker.Mock( 78 | side_effect=[raised_exc, expected_rdap_info]) 79 | 80 | module_mock = mocker.MagicMock( 81 | bootstrap=mocker.Mock, 82 | errors=whoisit.errors, 83 | domain=domain_method) 84 | mocker.patch("dns_deep_state.registry.whoisit", module_mock) 85 | 86 | reg = RegistryProbe() 87 | 88 | info = reg.domain_name("nic.work") 89 | 90 | assert info == expected_rdap_info 91 | 92 | 93 | def test_domain_rdap_other_query_error(mocker): 94 | """Replies from RDAP servers with too weak ssl should still function.""" 95 | mocker.patch("whoisit.bootstrap", mocker.Mock) 96 | raised_exc = whoisit.errors.QueryError("Some other error") 97 | domain_method = mocker.Mock(side_effect=raised_exc) 98 | mocker.patch("whoisit.domain", domain_method) 99 | 100 | reg = RegistryProbe() 101 | 102 | with pytest.raises(whoisit.errors.QueryError): 103 | reg.domain_name("nic.work") 104 | -------------------------------------------------------------------------------- /tests/test_report.py: -------------------------------------------------------------------------------- 1 | """Test the main module initialisation code. 2 | 3 | This should test that reports are generated as expected. The main module is the 4 | point of entry to this whole library so that's what we expect users will be 5 | using. 6 | 7 | It's also meant to be used as an CLI tool if called as a script. 8 | """ 9 | import copy 10 | import json 11 | from itertools import chain 12 | 13 | import pytest 14 | 15 | from dns_deep_state.report import DomainReport 16 | from dns_deep_state.exceptions import DomainError 17 | 18 | from .test_hosts import hosts_file 19 | from .test_registry import expected_rdap_info 20 | 21 | 22 | def domain_report_mocked_probes(mocker, probe_used=None, ipv6=True): 23 | """Instantiate DomainReport and mock out probes. 24 | 25 | If probe_used is not None, then one probe will be left untouched. 26 | 27 | Most probes tend to initialize some connection, or read a file in order to 28 | be ready to query something for information. When we're testing out 29 | individual reports, we don't need to initialize the probes that are not 30 | checked on every test. Also this initialization step can add up to consume 31 | quite a lot of time. We'll only test one desired probe at a time to keep 32 | the tests focused and quicker. 33 | """ 34 | probes = { 35 | "psl": "dns_deep_state.report.PublicSuffixList", 36 | "registry": "dns_deep_state.report.RegistryProbe", 37 | "dns": "dns_deep_state.report.DnsProbe", 38 | "local_hosts": "dns_deep_state.report.HostsProbe", 39 | } 40 | if probe_used not in probes.keys(): 41 | raise Exception("Unknown probe {probe_used}") 42 | 43 | for name, func in probes.items(): 44 | if name != probe_used: 45 | # Mock out any probe that wasn't requested for testing 46 | mocker.patch(func, mocker.MagicMock) 47 | 48 | if probe_used == "dns": 49 | mocker.patch('dns_deep_state.dns.DnsProbe._ipv6_connectivity', 50 | mocker.Mock(return_value=ipv6)) 51 | 52 | return DomainReport() 53 | 54 | 55 | def test_full_report_known_tld(mocker): 56 | """Checking a domain that uses one of the known "public suffixes". 57 | 58 | Note that we're only testing the processing that the full_report() method 59 | itself is doing, not any of the probe reports. 60 | """ 61 | # We still need to return an empty report for mocked out probes 62 | # for the tests on full_report() itself to be coherent. 63 | # Otherwise we get side-effects from the mocks themselves. 64 | patch_prefix = "dns_deep_state.report" 65 | for name in ["registry", "dns", "local_hosts"]: 66 | mocker.patch( 67 | f"{patch_prefix}.DomainReport.{name}_report", 68 | mocker.Mock(return_value={})) 69 | reporter = domain_report_mocked_probes(mocker, probe_used="psl") 70 | 71 | r = json.loads(reporter.full_report("example.com")) 72 | assert r["domain"] == "example.com" 73 | 74 | r2 = json.loads(reporter.full_report("www.example.com")) 75 | assert r2["domain"] == "example.com" 76 | 77 | 78 | def test_full_report_unknown_tld(mocker): 79 | """Checking a domain that doesn't have one of the "public suffixes". 80 | 81 | Note that we're only testing the processing that the full_report() method 82 | itself is doing, not any of the probe reports. 83 | """ 84 | reporter = domain_report_mocked_probes(mocker, probe_used="psl") 85 | 86 | with pytest.raises(ValueError): 87 | reporter.full_report("blah.patate") 88 | 89 | 90 | def test_registry_report(mocker): 91 | """Get a registry report for an existing domain name.""" 92 | module_mock = mocker.MagicMock(bootstrap=mocker.Mock) 93 | module_mock.domain = mocker.Mock(return_value=expected_rdap_info) 94 | mocker.patch("dns_deep_state.registry.whoisit", module_mock) 95 | reporter = domain_report_mocked_probes(mocker, probe_used="registry") 96 | 97 | r = reporter.registry_report("example.com") 98 | # The report should not contain all of the information returned by the 99 | # database. Only those informations help us determine if something's wrong 100 | # with the registration. 101 | assert len(r) == 4 102 | assert r["status"] == expected_rdap_info["status"] 103 | assert r["expiration_date"] == expected_rdap_info["expiration_date"] 104 | expctd_reg = expected_rdap_info["entities"]["registrar"][0]["name"] 105 | assert r["registrar"] == expctd_reg 106 | assert r["nameservers"] == expected_rdap_info["nameservers"] 107 | 108 | 109 | def test_dns_report_no_nameservers(mocker): 110 | """Can't find nameservers in DNS zone.""" 111 | raised_exc = DomainError( 112 | "No nameservers were found in DNS for example.com") 113 | dns_lookup = mocker.Mock(side_effect=raised_exc) 114 | mocker.patch("dns_deep_state.report.DnsProbe.name_servers", dns_lookup) 115 | reporter = domain_report_mocked_probes(mocker, probe_used="dns") 116 | 117 | with pytest.raises(DomainError): 118 | reporter.dns_report("example.com") 119 | 120 | 121 | @pytest.mark.parametrize("ipv6_enabled", [False, True]) 122 | def test_dns_report(mocker, ipv6_enabled): 123 | """Get all probed DNS information as a report.""" 124 | reporter = domain_report_mocked_probes(mocker, probe_used="dns", ipv6=ipv6_enabled) 125 | 126 | # We don't care at this level how the lookup is implemented. We only care 127 | # that when certain name servers are returned we get the proper form of 128 | # report. 129 | name_servers = {"ns1.example.com", "ns2.example.com", "ns3.example.com"} 130 | dns_lookup = mocker.Mock(return_value=name_servers) 131 | reporter.dns.name_servers = dns_lookup 132 | # In this scenario, all is going fine so we'll always return the same SOA 133 | # structure. 134 | soa_response = {"serial": "199974862"} 135 | reporter.dns.soa = mocker.Mock(return_value=soa_response) 136 | 137 | ns_v4_ips = [["127.0.0.121"], ["127.0.0.122"], ["127.0.0.123"]] 138 | reporter.dns.v4_address = mocker.Mock(side_effect=copy.deepcopy(ns_v4_ips)) 139 | 140 | all_ips = list(chain.from_iterable(ns_v4_ips)) 141 | if ipv6_enabled: 142 | ns_v6_ips = [["fe80::a"], ["fe80::b"], ["fe80::c"]] 143 | reporter.dns.v6_address = mocker.Mock(side_effect=copy.deepcopy(ns_v6_ips)) 144 | all_ips += list(chain.from_iterable(ns_v6_ips)) 145 | 146 | r = reporter.dns_report("example.com") 147 | 148 | # All went well: got one IPv4 and one IPv6 for each nameserver and all 149 | # responded with the same soa record information 150 | if ipv6_enabled: 151 | assert len(r["nameservers"]) == 6 152 | else: 153 | assert len(r["nameservers"]) == 3 154 | assert {x["hostname"] for x in r["nameservers"]} == name_servers 155 | 156 | all_found_ns_ips = [x["ip_address"] for x in r["nameservers"]] 157 | assert len(all_found_ns_ips) == len(all_ips) 158 | assert set(all_found_ns_ips) == set(all_ips) 159 | 160 | for ns in r["nameservers"]: 161 | assert ns["soa"]["serial"] == soa_response["serial"] 162 | 163 | 164 | def test_local_hosts_report(mocker): 165 | """Check presence in local hosts for a series of hosts. 166 | 167 | We want to see whether requesting multiple informations at once functions 168 | properly. That's why we're not parametrizing fixtures and checking them one 169 | at a time. 170 | """ 171 | # We need this mock before initializing the reporter, otherwise the call to 172 | # the real open() will happen during instantiation 173 | m = mocker.patch('builtins.open', mocker.mock_open(read_data=hosts_file)) 174 | reporter = domain_report_mocked_probes(mocker, probe_used="local_hosts") 175 | m.assert_called_once_with("/etc/hosts", "r") 176 | 177 | h_list = ["hostname.fqdn", "remote", "rem", "nope", "192.158.10.25"] 178 | 179 | rep = reporter.local_hosts_report(set(h_list)) 180 | expected = dict(zip(h_list, [True, True, False, False, False])) 181 | 182 | assert isinstance(rep, dict) 183 | for k, v in expected.items(): 184 | assert v == rep[k] 185 | --------------------------------------------------------------------------------