Liquid End – Access Tracker & Interactive Map

Liquid End is a lightweight web application for security researchers and teams to:

• Log access records (IP/host, ports, CVEs, notes, country).
• Visualize them on a dark‑theme, interactive choropleth map.
• Manage multiple users with admin/role separation.
• Export data to CSV, bulk delete, live ping test.

All data is stored in a single data.json file – no external database required.

---

📸 Screenshots

---

🚀 Quick Start

Prerequisites

• Python 3.8+ and pip

1. Clone & enter the project

git clone https://github.com/EynaExp/LiquidEnd.git
cd liquid-end

2. (Optional) Create a virtual environment

python -m venv venv
source venv/bin/activate      # Linux/macOS
venv\Scripts\activate         # Windows

3. Install dependencies

pip install flask folium pandas requests werkzeug

Or use requirements.txt:

pip install -r requirements.txt

4. Run the application

python LiquidEnd.py

5. Open your browser

Navigate to http://127.0.0.1:5000
The first visit will ask you to register an admin account – this user will have full control.

6. Register First admin account and use

Features

Feature Description

- Interactive Map	Choropleth map (dark theme) showing access counts per country. Click any coloured country to jump to its filtered list.

- Access List	DataTable with search, sort, pagination, inline copy button, live ping test, and bulk delete.

- Add Records	Form to insert new accesses. Required: IP/Host, Country (ISO2). Optional: Port, Service type, CVE, Note.

- Live Ping Test	Test reachability of IP/host on common ports (HTTP/HTTPS) directly from the list.

- Bulk Operations	Select multiple records → delete or ping them all at once.

- CSV Export	One‑click export of all your access data to a timestamped CSV file.

- User Management	First user is admin. Admins can add/edit/delete users, change roles, reset passwords.

- Secure Login	Passwords hashed with Werkzeug + simple math captcha to block basic bruteforce.

- Session Based	Each user sees only their own access entries.

- Data Structure

The file data.json is created automatically. Its schema:

{
  "users": {
    "alice": {
      "password": "scrypt:...",
      "role": "admin"
    }
  },
  "accesses": {
    "alice": [
      {
        "added_at": "2025-03-15 10:23:45",
        "ip_host": "192.168.1.100",
        "port": "443",
        "type": "HTTPS",
        "cve": "CVE-2024-12345",
        "note": "Test server",
        "country": "US"
      }
    ]
  },
  "config": {
    "theme": "dark",
    "map_zoom": 2
  }
}

Country codes must be valid ISO2 (e.g., US, GB, DE, IR). Unknown codes are stored but not displayed on the map.

⚙️ Configuration (inside LiquidEnd.py)

Variable	Purpose
app.secret_key	Change this to a long random string in production.
DB_FILE	Name of the JSON database (data.json).
ISO2_TO_ISO3 / ISO2_TO_NAME	Add more country mappings if needed.
geo_url	GeoJSON URL for world boundaries (default is reliable).
Security tip: For production, set debug=False and use a WSGI server like Gunicorn.

🖥️ Usage Examples

Add an access record
Login → click Add in the navbar.

Fill IP/Host, Port, Country (ISO2), and optional fields.

Submit – you’ll be redirected to the list.

Use the map
The Dashboard shows the map.

Countries with accesses are coloured (OrRd palette).

Hover to see country name and access count.

Click a country that has ≥1 access → automatically filters the list for that country.

Admin tasks

The Admin link appears only for admin users.

Add User – set username, password, role (user/admin).

Edit User – change password or role.

Delete User – you cannot delete your own account.

Export / Ping / Bulk delete
Export CSV – on the List page, downloads all your records.

Test button – checks if the host is reachable (HTTP/HTTPS on port 80/443 or custom port).

Select multiple rows → use Delete Selected or Ping Selected.

Create a requirements.txt with:

Flask==2.3.3
folium==0.15.1
pandas==2.1.4
requests==2.31.0
Werkzeug==2.3.0

🤝 Contributing

Feel free to open issues or pull requests for:

• Bug fixes

• New features (e.g., IP geolocation API, better captcha, file import)

• Documentation improvements

❓ FAQ

Map is empty?
Make sure your access records contain valid ISO2 country codes (e.g., US, GB). Unknown codes are ignored on the map.

Can I change the map style?
Yes – modify the tiles parameter in folium.Map() (e.g., "cartodb positron" for light theme).

How to back up my data?
Simply copy data.json. To restore, replace the file and restart the app.

The ping test says Down but the host is up?
The test uses a HEAD request with mode: 'no-cors'; some servers may block it. Use a dedicated ping tool for critical checks.

Educational Puprose only