.. OpenGlass documentation master file, created by
   sphinx-quickstart on Tue Feb  9 13:30:51 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to OpenGlass's documentation!
=====================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

OpenGlass is a tool to query various social network and search for different
types of information.

At this moment it is in it's alpha version and supports limited search functionalities
for Twitter_ and Telegram_.

OpenGlass was designed as an OSINT_ tool to identify and discover
disinformation campaigns.


.. _Twitter: https://www.twitter.com
.. _Telegram: https://www.telegram.org
.. _OSINT: https://en.wikipedia.org/wiki/Open-source_intelligence

=================
 Getting Started
=================

OpenGlass can be installed via pypi by running: ::

  $  pip install openglass

Then you can run it with: ::

  $  openglass --help

------------------------------
 Setup the configuration file
------------------------------

OpenGlass uses a config file in JSON format. A config_ example file is provided
in the code repository.

::

  {
    "twitter_apis": [
      {
        "CONSUMER_KEY": "CONSUMER_KEY",
        "CONSUMER_SECRET": "CONSUMER_SECRET",
        "ACCESS_KEY": "ACCESS_KEY",
        "ACCESS_SECRET": "ACCESS_SECRET"
      }
    ],
    "telegram": {
      "phone": "PHONE_NUMBER",
      "username": "USERNAME",
      "app_id": "APP_ID",
      "api_hash": "API_HASH",
      "servers": {
        "test": "149.154.167.40:443",
        "production": "149.154.167.50:443"
      }
    }
  }

To obtain API keys from Twitter_ and Telegram_ check their respective api docs:

* `Telegram api`_

* `Twitter api`_

.. _config: https://github.com/hiromipaw/openglass/blob/master/config.json.example
.. _`Telegram api`: https://core.telegram.org/api/obtaining_api_id
.. _`Twitter api`: https://developer.twitter.com/en/docs/twitter-api

-------------
 Run queries
-------------

To query telegram you need to use the ``--telegram`` switch

::

  --telegram
  --channel-users CHANNEL ID
                             Query telegram channels and return its users in json
  --channel-messages CHANNEL ID
                             Query telegram channels and return its messages in json
  --domains                  Parse links
  --channel-links            Parse links to telegram channels



To do a query in Telegram run:

::

  $  openglass --config config.json --telegram --channel-users "ChannelID"


The switch ` --csv ` prints result to a file called {query}-{timestamp}.csv

More specific queries are possible. Specifically the ``--domains`` switch returns
a list of high level domains (or FQDN_).

The ``--channel-links`` switch returns a list of shared telegram channels.

These two switch are important if you want to know which links are shared in a
Telegram_ channel and which other channels are cross referenced.

.. _FQDN: https://en.wikipedia.org/wiki/Fully_qualified_domain_name

Twitter_ support on openglass is still very experimental. In the next few versions
we hope to provide more analysis capabilities and the possibilities to run queries
using different APIs keys in order to avoid Twitter_'s query limits.

To do a query on twitter use the `--twitter switch`:

::

  --twitter
  --search SEARCH QUERY
                             Specify the term to search
  --timeline USERNAME OR ID
                             Specify the user to retrieve its timeline
  --profile USERNAME OR ID
                             Specify the user to retrieve its profile
  --followers USERNAME OR ID
                             Specify the user to retrieve its profile


Run a query with:

::

  $  openglass --config config.json --twitter --search "@twitter"


Openglass is in its first versions still. Please expect bugs.
If you want to contribute please do get in touch on Github_.


.. _Github: https://github.com/hiromipaw/openglass