Metadata-Version: 2.4
Name: TeleGramSight
Version: 0.4.0
Summary: Retrieve vulnerability sightings collected from Telegram and push them to a Vulnerability-Lookup instance.
License-Expression: GPL-3.0-or-later
License-File: COPYING
Keywords: Vulnerability-Lookup,vulnerability,cve,sighting,observations,Telegram
Author: Cédric Bonhomme
Author-email: cedric.bonhomme@circl.lu
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Requires-Dist: cryptography (>=46.0.7,<47.0)
Requires-Dist: dateparser (>=1.2,<2.0)
Requires-Dist: pyvulnerabilitylookup (>=2.0.0,<5.0.0)
Requires-Dist: requests (>=2.31,<3.0)
Project-URL: Changelog, https://github.com/cedricbonhomme/TeleGramSight/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/cedricbonhomme/TeleGramSight
Project-URL: Repository, https://github.com/cedricbonhomme/TeleGramSight
Description-Content-Type: text/markdown

# TeleGramSight

A client that retrieves vulnerability observations from a Telegram collector and pushes them to a
[Vulnerability-Lookup](https://github.com/vulnerability-lookup/vulnerability-lookup) instance.


## Installation


[pipx](https://github.com/pypa/pipx) is an easy way to install and run Python applications in isolated environments.
It's easy to [install](https://github.com/pypa/pipx?tab=readme-ov-file#on-linux).


```bash
$ pipx install TeleGramSight
$ export TeleGramSight_CONFIG=~/conf.py
```

The configuration should be defined in a Python file (e.g., ``~/.TeleGramSight/conf.py``).
You must then set an environment variable (``TeleGramSight_CONFIG``) with the full path to this file.


## Usage

Once installed and configured, invoke the CLI:

```bash
$ telegramsight --since 2026-04-23T00:00:00 --until 2026-04-24T00:00:00
$ telegramsight --since 'yesterday' --until 'today' --no-push
$ telegramsight --since '2 days ago' --until 'today'
$ telegramsight --since 1775001600 --until 1776902399
```

Arguments:

- `--since` / `--until` — time window bounds. Accept unix-epoch seconds,
  ISO 8601 timestamps, or natural-language expressions (e.g. `2 days ago`,
  `yesterday`, `today`, `1 week ago`). Defaults to the last 24 hours when
  omitted, which is the expected cron invocation.
- `--page-size` — results per API call (default 100).
- `--no-push` — dry run: fetch and build sightings and log them, but don't send anything to Vulnerability-Lookup.

Cron example (every hour):

```cron
0 * * * * TeleGramSight_CONFIG=/etc/telegramsight/conf.py /usr/local/bin/telegramsight
```

## Security

Sighting sources are encrypted with AES-SIV (RFC 5297) using the
`source_encryption_key` set in your configuration file. AES-SIV is used
deterministically (no nonce, no associated data) so that the same Telegram
message always produces the same source string, which lets Vulnerability-Lookup
deduplicate on the ciphertext without decrypting it. The key may be 32, 48, or
64 bytes (AES-128/192/256-SIV); 64 bytes is recommended for new deployments.
AES-256 retains an estimated ~128-bit security margin against known quantum
attacks (Grover's algorithm), but the tool itself has not been independently
audited or certified.

## License

[TeleGramSight](https://github.com/vulnerability-lookup/TeleGramSight) is licensed under
[GNU General Public License version 3](https://www.gnu.org/licenses/gpl-3.0.html)

~~~
Copyright (c) 2026 Computer Incident Response Center Luxembourg (CIRCL)
Copyright (C) 2026 Cédric Bonhomme - https://github.com/cedricbonhomme
~~~

