From 07a7a474f8eacd787a02103ead85146034fa717a Mon Sep 17 00:00:00 2001 From: Soxoj <31013580+soxoj@users.noreply.github.com> Date: Tue, 3 Dec 2024 17:25:17 +0100 Subject: [PATCH] Documentation update (#1926) --- README.md | 10 +++- docs/source/command-line-options.rst | 2 +- docs/source/conf.py | 2 +- .../extracting-information-from-pages.rst | 35 ------------ docs/source/features.rst | 37 ++++++++++++- docs/source/index.rst | 23 ++++++-- docs/source/installation.rst | 53 +++++++++++++++++++ docs/source/quick-start.rst | 21 ++++++++ 8 files changed, 140 insertions(+), 43 deletions(-) delete mode 100644 docs/source/extracting-information-from-pages.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/quick-start.rst diff --git a/README.md b/README.md index a0eacce..0db2d63 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,15 @@ For more information about development and contribution, please read the [develo [Full console output](https://raw.githubusercontent.com/soxoj/maigret/main/static/recursive_search.md) -### SOWEL classification +## Disclaimer + +**This tool is intended for educational and lawful purposes only.** The developers do not endorse or encourage any illegal activities or misuse of this tool. Regulations regarding the collection and use of personal data vary by country and region, including but not limited to GDPR in the EU, CCPA in the USA, and similar laws worldwide. + +It is your sole responsibility to ensure that your use of this tool complies with all applicable laws and regulations in your jurisdiction. Any illegal use of this tool is strictly prohibited, and you are fully accountable for your actions. + +The authors and developers of this tool bear no responsibility for any misuse or unlawful activities conducted by its users. + +## SOWEL classification This tool uses the following OSINT techniques: - [SOTL-2.2. Search For Accounts On Other Platforms](https://sowel.soxoj.com/other-platform-accounts) diff --git a/docs/source/command-line-options.rst b/docs/source/command-line-options.rst index 72cd86a..9d3b8ec 100644 --- a/docs/source/command-line-options.rst +++ b/docs/source/command-line-options.rst @@ -18,7 +18,7 @@ Parsing of account pages and online documents Maigret will try to extract information about the document/account owner (including username and other ids) and will make a search by the -extracted username and ids. See examples :doc:`in the separate section `. +extracted username and ids. See examples in the :ref:`extracting-information-from-pages` section. Main options ------------ diff --git a/docs/source/conf.py b/docs/source/conf.py index 4c04282..4039a90 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -3,7 +3,7 @@ # -- Project information project = 'Maigret' -copyright = '2021, soxoj' +copyright = '2024, soxoj' author = 'soxoj' release = '0.4.4' diff --git a/docs/source/extracting-information-from-pages.rst b/docs/source/extracting-information-from-pages.rst deleted file mode 100644 index c24e6d5..0000000 --- a/docs/source/extracting-information-from-pages.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. _extracting-information-from-pages: - -Extracting information from pages -================================= -Maigret can parse URLs and content of web pages by URLs to extract info about account owner and other meta information. - -You must specify the URL with the option ``--parse``, it's can be a link to an account or an online document. List of supported sites `see here `_. - -After the end of the parsing phase, Maigret will start the search phase by :doc:`supported identifiers ` found (usernames, ids, etc.). - -Examples --------- -.. code-block:: console - - $ maigret --parse https://docs.google.com/spreadsheets/d/1HtZKMLRXNsZ0HjtBmo0Gi03nUPiJIA4CC4jTYbCAnXw/edit\#gid\=0 - - Scanning webpage by URL https://docs.google.com/spreadsheets/d/1HtZKMLRXNsZ0HjtBmo0Gi03nUPiJIA4CC4jTYbCAnXw/edit#gid=0... - ┣╸org_name: Gooten - ┗╸mime_type: application/vnd.google-apps.ritz - Scanning webpage by URL https://clients6.google.com/drive/v2beta/files/1HtZKMLRXNsZ0HjtBmo0Gi03nUPiJIA4CC4jTYbCAnXw?fields=alternateLink%2CcopyRequiresWriterPermission%2CcreatedDate%2Cdescription%2CdriveId%2CfileSize%2CiconLink%2Cid%2Clabels(starred%2C%20trashed)%2ClastViewedByMeDate%2CmodifiedDate%2Cshared%2CteamDriveId%2CuserPermission(id%2Cname%2CemailAddress%2Cdomain%2Crole%2CadditionalRoles%2CphotoLink%2Ctype%2CwithLink)%2Cpermissions(id%2Cname%2CemailAddress%2Cdomain%2Crole%2CadditionalRoles%2CphotoLink%2Ctype%2CwithLink)%2Cparents(id)%2Ccapabilities(canMoveItemWithinDrive%2CcanMoveItemOutOfDrive%2CcanMoveItemOutOfTeamDrive%2CcanAddChildren%2CcanEdit%2CcanDownload%2CcanComment%2CcanMoveChildrenWithinDrive%2CcanRename%2CcanRemoveChildren%2CcanMoveItemIntoTeamDrive)%2Ckind&supportsTeamDrives=true&enforceSingleParent=true&key=AIzaSyC1eQ1xj69IdTMeii5r7brs3R90eck-m7k... - ┣╸created_at: 2016-02-16T18:51:52.021Z - ┣╸updated_at: 2019-10-23T17:15:47.157Z - ┣╸gaia_id: 15696155517366416778 - ┣╸fullname: Nadia Burgess - ┣╸email: nadia@gooten.com - ┣╸image: https://lh3.googleusercontent.com/a-/AOh14GheZe1CyNa3NeJInWAl70qkip4oJ7qLsD8vDy6X=s64 - ┗╸email_username: nadia - -.. code-block:: console - - $ maigret.py --parse https://steamcommunity.com/profiles/76561199113454789 - Scanning webpage by URL https://steamcommunity.com/profiles/76561199113454789... - ┣╸steam_id: 76561199113454789 - ┣╸nickname: Pok - ┗╸username: Machine42 diff --git a/docs/source/features.rst b/docs/source/features.rst index 6fa2a39..0ecd1c8 100644 --- a/docs/source/features.rst +++ b/docs/source/features.rst @@ -77,7 +77,7 @@ Enabled by default, can be disabled with ``--no-recursion``. ... Username permutations --------------------- +--------------------- Maigret can generate permutations of usernames. Just pass a few usernames in the CLI and use ``--permute`` flag. Thanks to `@balestek `_ for the idea and implementation. @@ -153,6 +153,41 @@ The Maigret database contains not only the original websites, but also mirrors, It allows getting additional info about the person and checking the existence of the account even if the main site is unavailable (bot protection, captcha, etc.) +.. _extracting-information-from-pages: + +Extracting information from pages +--------------------------------- +Maigret can parse URLs and content of web pages by URLs to extract info about account owner and other meta information. + +You must specify the URL with the option ``--parse``, it's can be a link to an account or an online document. List of supported sites `see here `_. + +After the end of the parsing phase, Maigret will start the search phase by :doc:`supported identifiers ` found (usernames, ids, etc.). + +.. code-block:: console + + $ maigret --parse https://docs.google.com/spreadsheets/d/1HtZKMLRXNsZ0HjtBmo0Gi03nUPiJIA4CC4jTYbCAnXw/edit\#gid\=0 + + Scanning webpage by URL https://docs.google.com/spreadsheets/d/1HtZKMLRXNsZ0HjtBmo0Gi03nUPiJIA4CC4jTYbCAnXw/edit#gid=0... + ┣╸org_name: Gooten + ┗╸mime_type: application/vnd.google-apps.ritz + Scanning webpage by URL https://clients6.google.com/drive/v2beta/files/1HtZKMLRXNsZ0HjtBmo0Gi03nUPiJIA4CC4jTYbCAnXw?fields=alternateLink%2CcopyRequiresWriterPermission%2CcreatedDate%2Cdescription%2CdriveId%2CfileSize%2CiconLink%2Cid%2Clabels(starred%2C%20trashed)%2ClastViewedByMeDate%2CmodifiedDate%2Cshared%2CteamDriveId%2CuserPermission(id%2Cname%2CemailAddress%2Cdomain%2Crole%2CadditionalRoles%2CphotoLink%2Ctype%2CwithLink)%2Cpermissions(id%2Cname%2CemailAddress%2Cdomain%2Crole%2CadditionalRoles%2CphotoLink%2Ctype%2CwithLink)%2Cparents(id)%2Ccapabilities(canMoveItemWithinDrive%2CcanMoveItemOutOfDrive%2CcanMoveItemOutOfTeamDrive%2CcanAddChildren%2CcanEdit%2CcanDownload%2CcanComment%2CcanMoveChildrenWithinDrive%2CcanRename%2CcanRemoveChildren%2CcanMoveItemIntoTeamDrive)%2Ckind&supportsTeamDrives=true&enforceSingleParent=true&key=AIzaSyC1eQ1xj69IdTMeii5r7brs3R90eck-m7k... + ┣╸created_at: 2016-02-16T18:51:52.021Z + ┣╸updated_at: 2019-10-23T17:15:47.157Z + ┣╸gaia_id: 15696155517366416778 + ┣╸fullname: Nadia Burgess + ┣╸email: nadia@gooten.com + ┣╸image: https://lh3.googleusercontent.com/a-/AOh14GheZe1CyNa3NeJInWAl70qkip4oJ7qLsD8vDy6X=s64 + ┗╸email_username: nadia + +.. code-block:: console + + $ maigret.py --parse https://steamcommunity.com/profiles/76561199113454789 + Scanning webpage by URL https://steamcommunity.com/profiles/76561199113454789... + ┣╸steam_id: 76561199113454789 + ┣╸nickname: Pok + ┗╸username: Machine42 + + Simple API ---------- diff --git a/docs/source/index.rst b/docs/source/index.rst index b42b8c5..a54b1d9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,21 +10,36 @@ This is achieved by checking for accounts on a huge number of sites and gatherin The project's main goal — give to OSINT researchers and pentesters a **universal tool** to get maximum information about a person of interest by a username and integrate it with other tools in automatization pipelines. +.. warning:: + **This tool is intended for educational and lawful purposes only.** + The developers do not endorse or encourage any illegal activities or misuse of this tool. + Regulations regarding the collection and use of personal data vary by country and region, + including but not limited to GDPR in the EU, CCPA in the USA, and similar laws worldwide. + + It is your sole responsibility to ensure that your use of this tool complies with all applicable laws + and regulations in your jurisdiction. Any illegal use of this tool is strictly prohibited, + and you are fully accountable for your actions. + + The authors and developers of this tool bear no responsibility for any misuse + or unlawful activities conducted by its users. + You may be interested in: ------------------------- -- :doc:`Command line options description ` and :doc:`usage examples ` +- :doc:`Quick start ` +- :doc:`Command line options description ` +- :doc:`Usage examples ` - :doc:`Features list ` -- :doc:`Project roadmap ` .. toctree:: :hidden: :caption: Sections - command-line-options + quick-start + installation usage-examples + command-line-options features philosophy - extracting-information-from-pages supported-identifier-types tags settings diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..bd1d3ba --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,53 @@ +.. _installation: + +Installation +============ + +Package installing +------------------ + +Please note that the sites database in the PyPI package may be outdated. +If you encounter frequent false positive results, we recommend installing the latest development version from GitHub instead. + +.. note:: + Python 3.10 or higher and pip is required, **Python 3.11 is recommended.** + +.. code-block:: bash + + # install from pypi + pip3 install maigret + + # usage + maigret username + +Development version (GitHub) +---------------------------- + +.. code-block:: bash + + git clone https://github.com/soxoj/maigret && cd maigret + pip3 install . + + # OR + pip3 install git+https://github.com/soxoj/maigret.git + + # usage + maigret username + + # OR use poetry in case you plan to develop Maigret + pip3 install poetry + poetry run maigret + +Docker +------ + +.. code-block:: bash + + # official image of the development version, updated from the github repo + docker pull soxoj/maigret + + # usage + docker run -v /mydir:/app/reports soxoj/maigret:latest username --html + + # manual build + docker build -t maigret . diff --git a/docs/source/quick-start.rst b/docs/source/quick-start.rst new file mode 100644 index 0000000..ff687ae --- /dev/null +++ b/docs/source/quick-start.rst @@ -0,0 +1,21 @@ +.. _quick-start: + +Quick start +=========== + +After :doc:`installing Maigret `, you can begin searching by providing one or more usernames to look up: + +``maigret username1 username2 ...`` + +Maigret will search for accounts with the specified usernames across a vast number of websites. It will provide you with a list +of URLs to any discovered accounts, along with relevant information extracted from those profiles. + +.. note:: + Maigret will search for accounts on a huge number of sites, + and some of them may return false positive results. At the moment, we are working on autorepair mode to deliver + the most accurate results. + + If you experience many false positives, you can do the following: + + - Install the last development version of Maigret from GitHub + - Run Maigret with ``--self-check`` flag and agree on disabling of problematic sites