Using Lupus

Overview & responsible use

Lupus is a self-contained offensive-security workspace for Android. It bundles a full Metasploit Framework, PostgreSQL, Nmap and a terminal environment, and wraps them in a touch UI: scan a target, collect the results in a workspace database, launch exploits and auxiliary modules, and drive the sessions you land — all from the phone.

The engine can run in two places: locally, directly on the device, or on a remote agent you connect to. The rest of the app works the same either way.

Create your account

Lupus is tied to a Lupus account — that account is what carries your Pro entitlement across devices and builds. On first launch you land on the sign-in screen.

1 · Sign in screen

Enter your email and password to sign in, use Continue with Google, or tap Create account at the bottom if you don't have one yet. Forgot password? starts the reset flow (you'll get a reset email).

2 · Create account

Provide your email, a password (minimum 8 characters) and confirm it, then tap Create. The account is provisioned and a 6-digit confirmation code is emailed to you.

3 · The confirmation email

Within a few seconds you receive a “Confirm your Lupus account” email containing a 6-digit code. The code expires in 15 minutes. If it doesn't arrive, check your spam/promotions folder and use Resend code.

4 · Verify

Type the 6 digits into the Verify account screen and tap Verify. Your account is now confirmed and you're taken into the app.

Activating Pro & how to pay

The free tier covers scanning, the workspace database, browsing exploits/auxiliary, running modules and opening a session. Pro unlocks the advanced workflow: editing the database, Nuclei, msfvenom, payload handlers, import/export, unlimited background tasks, and the full post-exploitation toolkit (file explorer, process manager, post modules).

Pro is tied to your account, not the device: pay once and sign in anywhere — the app re-checks your entitlement on sign-in and unlocks automatically. Whenever you open a gated feature on the free tier, you'll see this upgrade card, which routes you to the payment options:

Plans

Three plans, all unlocking the same Pro features — pick the billing that suits you:

• Monthly — recurring, cancel anytime (includes a free trial).
• Annual — recurring yearly, the best value.
• Lifetime — pay once, no subscription.

Prices are in USD.

How to pay

There are three payment rails, all ending in the same account-based Pro unlock:

• Google Play (in-app) — tap a plan (Yearly / Monthly / Lifetime) on the in-app Pro card and complete the purchase through Google Play billing.
• Card / PayPal (web) — on the in-app card tap Other ways to pay (or open the pricing page in a browser) and use the Get plan button to check out with a card or PayPal.
• Crypto (web) — on the pricing page use Pay with crypto to pay in BTC, ETH and other assets; Pro is granted automatically once the payment confirms.

First launch: choose a mode

After verifying, Lupus asks for two permissions and then how it should run:

• Notifications — so long-running scans and jobs can report progress.
• All files access — Lupus stores its Metasploit environment, loot and database on the device, so it needs full file access. Tap Continue and enable Allow access to manage all files in the system screen that opens.

Then you choose the engine: local (run everything on the phone) or remote (connect to an agent). You can switch later; this is just the starting point.

Local mode

Local mode runs the whole stack on the device. Tap Switch to local Metasploit and confirm the install prompt. Lupus then unpacks a self-contained environment — Ruby, the Metasploit Framework, PostgreSQL and Nmap built for your device's architecture.

When setup finishes, the engine starts (PostgreSQL + the Metasploit RPC) and you land in the main workspace. Everything you scan and exploit runs from the phone itself.

Remote mode & the agent

Remote mode points Lupus at an app-agent running on another machine — a VPS, a lab box or a server — so the heavy lifting happens there and the phone is just the console. Use it for more horsepower, long engagements, or to attack from a network the agent already sits on.

What the agent is

The agent (app-agent) is a single gRPC server that is Lupus's only point of contact with the box. Everything the app does flows through it: running tools (nmap, nuclei), proxying the Metasploit RPC, exposing the Metasploit database (hosts, services, vulns, credentials, loots, workspaces), driving consoles and sessions, generating payloads, and browsing/transferring files — it replaces the old SSH/SFTP/exec paths. The phone never talks to Metasploit directly; it talks to the agent.

Prerequisites

The host running the agent needs:

• A Linux machine you control.
• Metasploit Framework installed (it provides msfrpcd).
• PostgreSQL for the Metasploit database.
• The scanning tools you intend to use (nmap, nuclei).
• The app-agent binary — grab it from the download page (it's distributed separately from the app).
• Network reach — the agent's port must be reachable from the phone.

This is exactly the stack Lupus bundles and starts for you in local mode; on a remote box you run the same pieces yourself.

Services that must be running

Bring them up in this order — each depends on the previous:

1. PostgreSQL — the Metasploit database (a msf role/database on 127.0.0.1:5432).
2. msfrpcd — the Metasploit RPC daemon, e.g. msfrpcd -U lupus -P <password> -a 127.0.0.1 -p 55599.
3. app-agent — the gRPC server on :50051, pointed at msfrpcd.

Quick start

Grab the agent from the download page (a static Linux binary). Start PostgreSQL and msfrpcd, then launch the agent in enrollment mode — it auto-generates its TLS certificates into --certs-dir:

chmod +x app-agent-linux-amd64

# msfrpcd (example): msfrpcd -U app -P app -S -p 55599 -a 127.0.0.1
./app-agent-linux-amd64 \
  --listen 0.0.0.0:50051 \
  --certs-dir ~/.app-agent/certs --cert-sans "<your-public-ip>" \
  --msf-host 127.0.0.1 --msf-port 55599 --msf-user app --msf-pass app --msf-ssl=true \
  --enrollment-mode --allowed-ips "<your-phone-ip>/32"

The agent prints an 8-character enrollment code. Enter the host, port 50051 and that code in the app (below). Only port 50051 needs to be reachable from the phone — keep PostgreSQL and msfrpcd bound to 127.0.0.1.

Agent options

The agent is configured with flags (the --msf-* example above matches an msfrpcd on port 55599):

Enrolling & connecting

First run — start the agent with --enrollment-mode; it prints a one-time 8-character enrollment code on its console. On the app's connection screen, fill in:

• Host — the agent's IP or hostname.
• Port — the agent's gRPC port (default 50051).
• Enrollment code — the 8-character code.

Tap Enroll & Connect. Lupus performs a trust-on-first-use enrollment: the agent hands back a CA certificate, a client certificate/key and an auth token; the app stores them securely and verifies the link with a ping. On later restarts, run the agent in its normal mode (no enrollment flag) — the app reuses the saved certificates and token, so you don't enroll again.

Security

After enrollment, every call is mutually authenticated with mTLS (CA + client certificate) plus a bearer token, established trust-on-first-use during enrollment. The Metasploit RPC password is never passed on the command line — the agent reads it from a file (--msf-pass-file), so it never shows up in the process list.

Checking status & troubleshooting

Settings → Global shows the agent state — Connected / Disconnected and Enrolled / Not enrolled.

• Enrollment fails — the agent isn't running in --enrollment-mode, the code is wrong/expired, or the host/port isn't reachable from the phone.
• Connected but no Metasploit data — msf_connected = false; msfrpcd (or Postgres) isn't up. Restart the service stack in order.
• After a reconnect — keep the saved connection; don't re-enroll unless you've reset the agent's certificates.

The main menu

The hamburger (☰) at the top-left opens the navigation drawer — your index to every module, grouped into sections:

• Top: Exploits, Auxiliary, Payload Handlers, Msfconsole, Msfvenom, Jobs, Settings.
• Database: Workspaces, Loots, Hosts, Services, Credentials, Vulnerabilities.
• Scanning: Import, Export, Nmap, Nuclei.
• Remote: Sessions.

The badge at the top-right is the background tasks stack (covered below); the “⋮” menu holds per-screen actions.

Scanning — Nmap

Nmap is usually your first step: discover a host and its open services, which then populate the workspace database. Open Nmap from the Scanning section.

Options, one by one

• Scan profile — a preset (e.g. Quick scan). The icon at the top-right switches profiles; each profile sets a different command.
• Target — a single host, a range or a CIDR (e.g. 192.168.122.200 or 192.168.1.0/24). What you type here is appended to the command.
• Command — the actual db_nmap line, fully editable if you want custom flags. The db_ prefix means results are written straight into the workspace.
• Nmap console — live output streams here while the scan runs.
• Start scan — runs it; the button becomes a stop control while active.

Scanning — Nuclei Pro

Nuclei runs thousands of community vulnerability templates against your targets and writes findings into the workspace as vulnerabilities. It's a short wizard:

• Target — enter an IP, domain or URL, and choose common ports (80, 443) or a custom set.
• Templates — pick Quick (CVEs, misconfigurations, exposures) or Advanced to choose specific template groups.
• Run — launch the scan; the console streams progress (templates loaded, requests, findings) and matches land in Vulnerabilities.

The workspace database

Everything you discover is stored in a Metasploit workspace. The Database section gives each record type its own searchable, filterable screen. Viewing is free; creating and editing records is Pro.

Workspaces

A workspace is an isolated project — keep each engagement separate. The registry shows the active workspace with a live count of hosts, services, vulns, creds, loots and notes. Use + New workspace to start a fresh one.

Hosts & Services

Hosts lists every discovered machine with OS-type filter chips (Windows / Linux / macOS) and a search box; each row has quick actions to re-scan it with Nmap or Nuclei. Services lists every open port/service across the workspace, filterable by state (Open / Closed / Filtered). Both feed directly off your scans.

Vulnerabilities, Credentials & Loots

Vulnerabilities collects findings (from Nuclei or exploited modules), filterable by severity. Credentials stores captured logins (Password / NTLM / SSH-Key). Loots holds files and data pulled from targets. They fill up as you run vuln scans and land sessions.

Import & export Pro

Move workspace data in and out of Lupus — handy for continuing an engagement started elsewhere or archiving results.

Import

Feed an existing scan/database file into the workspace. Choose a source file (a local file or one already in the Metasploit directory) and tap Start import; the console streams db_import as records are added.

Export

Write the current workspace out as a report. Choose a destination (this device or a server directory) and tap Start export; the console streams db_export.

Exploits

The Exploits module is the full Metasploit exploit catalog, searchable by name. Find a module, open it, configure it and run it.

Browse & open

Search (e.g. ms17_010_eternalblue) and tap a result to open its detail screen.

Configure the options (datastore)

The detail screen exposes the module's datastore. Set the Target and Payload, fill required options — most importantly RHOSTS (the target host) — and toggle any flags (e.g. VERIFY_TARGET). Optional fields show their hint text. Then tap Exploit.

Run it

The console streams the attempt in real time — target validation, exploitation, and the result. If it succeeds you get a session (see Sessions); the run can also continue as a background job.

Auxiliary

Auxiliary modules are everything that isn't a direct exploit — scanners, fuzzers, brute-forcers, spoofers, gatherers and admin tools. The module works exactly like Exploits: search the catalog, open a module, set its options, and run it, with output streaming to the console and results landing in the database.

Payloads & handlers Pro

Msfvenom

Generate standalone payloads (executables, scripts, shellcode) for delivery. Search the full payload list, pick one, then configure it: LHOST/LPORT, encoders and advanced options, plus the output path/file. Tap Generate to produce the artifact.

Payload Handlers

Start, stop and configure listeners (multi/handler) that catch connections from the payloads you deliver. Pick the matching payload, set LHOST/LPORT and tap Start handler; when a foothold connects it appears in Sessions.

msfconsole

When you want the raw interface, Msfconsole gives you the interactive Metasploit shell. Type any msfconsole command at the prompt and the output streams back — the same engine that powers the touch modules, with nothing in the way. Great for one-off commands, search, db_ commands and anything not surfaced as a dedicated screen.

Sessions & post-exploitation

When an exploit or handler lands, the foothold appears in Sessions — the live control grid, with counts of total / Meterpreter / shell sessions. Each session shows its type, platform, architecture, target and route. Opening a session is free; the full post-exploitation toolkit is Pro.

Inside a session Pro

Tap a session to open its control surface. A left rail switches between tabs — Shell, Files, Procs, Post, Core, Net and Surv.:

• Shell — an interactive Meterpreter (or command) prompt; type any command and the output streams back.
• Files — browse the target's filesystem and download/upload files.
• Procs — list running processes, migrate into one, or kill it.
• Post — search and run Metasploit post-exploitation modules against the session.
• Core / Net / Surv. — session core commands, networking/pivoting, and surveillance helpers.

Jobs & background tasks

Jobs lists Metasploit background jobs — running handlers, scanners and exploits that continue after you leave their screen. Open it to see what's active and stop a job.

Background tasks (the badge at the top-right) is Lupus's own multitasking stack: it saves the context of screens you've opened so you can resume them instantly or swipe them away. The free tier keeps up to 3; Pro is unlimited.

Settings

Settings has three sections down the left side:

• Global — the agent connection status and an Execute as root toggle.
• Database — Clean database permanently wipes all pentest data (workspaces, hosts, services, vulns, credentials, loots). App settings are kept. This can't be undone.
• Metasploit — the framework and loot paths in use by the engine.

Troubleshooting

The confirmation code never arrives

Check your spam/promotions folder and search for no-reply@alpistesec.com. Use Resend code — the code expires after 15 minutes, so always use the newest one. Mark the message as “not spam” so future emails land in your inbox.

The agent won't connect

Make sure the agent is running in enrollment mode, the host/port are reachable from the phone, and you're using a fresh enrollment code. After the first successful enrollment, keep the saved connection instead of enrolling again.

I want to start over

Use Settings → Database → Clean database to wipe pentest data while keeping the app configured, or create a new Workspace to keep a clean slate per engagement.

Still stuck? Contact support — or see all features and pricing.