# Periscope

Periscope is a local desktop application for ingesting large newline-delimited JSON (NDJSON) Shodan exports into SQLite, then searching, filtering, cross-referencing, analyzing, and exporting the results.

It is designed for large local datasets and avoids loading the full source file into memory.

## Features

- Stream-ingests large Shodan NDJSON exports into SQLite
- Search across IP, org, ASN, port, title, server banner, raw payload, and geography
- Cross-reference records by shared values such as IP, org, ASN, port, title, and server
- Quick analytics for top ports, countries, organizations, titles, and banners
- Export current results to CSV or JSON
- Dark desktop UI built with Tkinter + ttk
- Zero external database dependency

## Project layout

```text
periscope_full_project/
├── app.py
├── README.md
├── requirements.txt
├── launch.sh
├── exports/
├── data/
└── periscope/
    ├── __init__.py
    ├── config.py
    ├── db.py
    ├── importer.py
    ├── exporter.py
    ├── analytics.py
    ├── models.py
    ├── utils.py
    ├── core/
    │   └── query_builder.py
    └── ui/
        ├── main_window.py
        └── theme.py
```

## Requirements

- Python 3.10+
- Tkinter available in your Python install

## Install

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Run

```bash
python3 app.py
```

Or:

```bash
chmod +x launch.sh
./launch.sh
```

## First use

1. Launch the app.
2. Choose your Shodan NDJSON file.
3. Import it into SQLite.
4. Search or filter records.
5. Cross-reference selected rows.
6. Export results.

## Notes on file format

This project expects Shodan export data in newline-delimited JSON format, where each line is a standalone JSON object.

Example:

```json
{"ip_str":"1.2.3.4","port":80,"org":"Example ISP"}
{"ip_str":"5.6.7.8","port":443,"org":"Another Org"}
```

## Database schema

Main table: `hosts`

Indexed fields include:
- ip_str
- port
- org
- asn
- country_name
- city
- http_title
- server
- product
- timestamp

## Safety and intent

This application is for local analysis and defensive research workflows. It does not scan, attack, or contact remote systems.

## License

Use, modify, and extend locally as needed.
