AstralOSINT Field Manual

Read This First

AstralOSINT is a mapping and analysis console for open-source intelligence (OSINT) research — the practice of gathering and analyzing information that is already publicly available. It's built for training, journalism, humanitarian mapping, and security research use cases.

Everything in this manual maps directly to a real tab or button in the console — there's nothing here that isn't in the app. Screenshots are kept to the essentials; most controls are shown as small inline reproductions of the actual UI so you can recognize them at a glance.

Installation & Setup

AstralOSINT runs two ways: as a proper Electron desktop app (recommended), or as a zero-install browser fallback. Both ship in the same repository.

1.1 Requirements before you start

• Desktop app: Node.js + npm (the setup script installs these automatically on Debian/Ubuntu/Kali, Termux, macOS with Homebrew, or Arch — otherwise install Node manually first).
• Browser fallback: Python 3 only, nothing else.
• An internet connection — map tiles, geocoding, routing, and the Line of Sight tool's elevation lookups are all pulled live.

1.2 Quick Start (Desktop App)

From inside the extracted or cloned AstralOSINT folder:

./setup.sh   # one-time: installs Node deps + Electron
./start.sh   # launches the desktop console

setup.sh checks for Node/npm, installs them if missing, then runs npm install inside hud/. start.sh just confirms that install happened and runs npm start.

1.3 Browser Fallback no Node required

Prefer not to install Electron? Run:

./run.sh

This opens a small menu — option 1 starts a local Python server on localhost:8080 and opens it in your default browser. It's the same interface, just without the native desktop shell (no OS-level save dialogs, no system tray).

1.4 Installing as a Desktop Menu App Kali / Debian-based

To get AstralOSINT in your applications menu with its own launcher command:

./packaging/install.sh

This installs per-user (no root needed for the app itself) to:

To remove everything the installer created:

./packaging/uninstall.sh

Interface Orientation

2.1 The Console

The whole app is one full-screen map with a collapsible sidebar console. Click the menu icon (☰) top-left to open or close it. Inside, six tabs cover every function:

The HUD strip along the top-right of the map shows the live UTC clock, your cursor's coordinates, current zoom level, and a connection status indicator.

2.2 Designating a Target

Almost everything in AstralOSINT revolves around one concept: the currently designated target — a single lat/lng pair the whole console reads from and writes to. You designate one by:

• Clicking anywhere on the map (this also reverse-geocodes the address automatically), or
• Running a search and selecting a result (§3), or
• Using Locate My Position on the Search tab.

Once designated, the target's coordinates populate the Latitude/Longitude/Address fields on the Intel tab — and any tool with a Use Current Target or Use Target button (Shadow, Coordinates, Triangulate, Line of Sight) can pull those same coordinates in with one click, so you're never retyping a location between tools.

2.3 Keyboard Shortcuts

Search & Positioning

The Search tab is the front door: a global place/address search, plus a Locate My Position button that centers the map on your own device location. Search results, once selected, both jump the map and designate a target — ready to tag or hand off to any other tool.

Layers

The Layers tab controls what's drawn on top of the base map: imagery style, marker clustering, and two live analysis overlays.

4.1 Imagery & Clustering

Switch between Street, Satellite, Terrain, and Tactical base map styles. Marker clustering groups nearby saved targets into a single expandable cluster once you zoom out — turn it off if you'd rather see every pin individually, even overlapping.

4.2 Day / Night Terminator Analysis Layers

Shades the current night hemisphere on the map and drops a marker at the sub-solar point — the exact spot on Earth directly under the sun right now. It refreshes every 60 seconds. This is the same geometry behind shadow-based photo geolocation (§7) — useful for building intuition about where the sun is before you start solving for a specific time.

4.3 Target Density Heatmap Analysis Layers

Renders your saved Intel log (§5) as a heatmap instead of individual pins, so dense clusters of targets are visible at a glance. It updates live — save, delete, or import targets while it's on and the heatmap redraws automatically.

Intel Log

This is your running case file — every target you've saved, each with a name, tag, and optional note.

5.1 Tagging & Saving

With a target designated (§2.2), give it a name, pick a tag, and save. Tags are visual shorthand for what a pin represents:

Saved targets appear as markers on the map (grouped by the clustering setting in §4.1) and in a scrollable list in the Intel tab, with the running count shown in the tab's badge.

5.2 Export & Import

Export writes your whole Intel log to a JSON file — in the desktop app, a native save dialog; in the browser fallback, a normal file download. Import reads one of those files back in, merging it into your current log.

Tactical Routing

Pick any two saved targets as a start and end point, and the Route tab plots a path between them with distance and duration. Useful for planning ground movement between points of interest, or just understanding how two locations in your case relate spatially. Clear removes the current route without touching your saved targets.

Shadow Calculator

This is where AstralOSINT moves from mapping into photo geolocation tradecraft. Every object under the sun casts a shadow whose length and direction depend entirely on where you are on Earth and what time it is — which means a shadow in a photo is a clue you can work backward from.

7.1 Check Time

Enter a candidate location and a UTC date/time, and it tells you exactly where the sun is: elevation above the horizon, compass azimuth, and which way a shadow would point. Use this to sanity-check a hypothesis — "if this photo was taken here at this time, would the shadows look like this?"

7.2 Find Matching Times

The reverse — and more powerful — direction. Measure an object's height and its shadow's length in the photo (a fence post, a doorframe, a person of known height), enter those, pick a candidate location and date, and it scans the entire day to find the UTC time(s) that would produce that exact shadow. Add the shadow's compass direction to narrow a two-answer result (morning vs. afternoon) down to one.

Analyst Tools

Three focused calculators live under the Tools tab, switchable with the toggle at the top of the panel:

8.1 Coordinate Converter

Converts freely between the four ways a location gets written: Decimal degrees, DMS (degrees/minutes/seconds), UTM, and MGRS — the grid reference format NATO and most military/government mapping systems use (e.g. 31U DQ 48252 11954). Enter a coordinate in any one format and get all four back, with a one-click Jump to Map.

8.2 Triangulation

Classic cross-bearing resection: if you have two or more vantage points and a compass bearing toward the same target from each (from multiple photos/videos of the same object, or direction-finding), this plots where those bearing lines intersect. Add a third or more points for a best-fit estimate with a reported error margin instead of a single exact crossing.

8.3 Line of Sight

Checks whether an observer and a target point can actually see each other — pulling real elevation data along the path and accounting for the Earth's curvature and standard atmospheric refraction, not just a flat assumption. Enter both points' height above ground (eye height, building height, mast height), and it returns a clear CLEAR / OBSTRUCTED verdict plus a visual elevation profile.

Worked Example: Geolocating a Photo

A short case study showing how the tools in §7 and §8 combine in an actual investigation — verifying where and when a photo was taken, using only what's visible in the frame.

1. Narrow the region. Use visible clues in the photo — signage, architecture, vegetation, license plates, terrain — to identify a shortlist of candidate locations. Search each one (§3) to see it on the map.
2. Measure the shadow. Find a vertical object with a known or estimable height in the photo (a lamppost, a doorway, a person) and measure its shadow length relative to it, even roughly.
3. Run Find Matching Times (§7.2) for your top candidate location and a plausible date range. Add the shadow's compass direction if you can estimate it from the photo (e.g. from a compass app, or known street orientation) to narrow morning vs. afternoon.
4. Cross-check with Line of Sight (§8.3) if the photo shows a distant landmark — confirm that landmark would actually be visible from your candidate point given the terrain between them.
5. If you have a second photo or witness bearing to the same subject from a different angle, run Triangulation (§8.2) to cross-check your candidate point independently.
6. Convert and record. Once confident, use the Coordinate Converter (§8.1) to get the location in whatever format your report needs, then save it to the Intel log (§5.1) with your supporting notes.

Field Reference

Full setup commands, gathered in one place:

./setup.sh              # one-time dependency install
./start.sh              # launch desktop app
./run.sh                # browser fallback, no install needed
./packaging/install.sh  # install to applications menu
./packaging/uninstall.sh