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, your own custom modules and payload files, 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, an upgrade card explains what it unlocks and 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.
• Team — billed per seat, one subscription for the whole team. See Teams & shared engagements.

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) 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.

Teams & shared engagements

What the team shares

Everyone points their phone at the same agent, so everyone works the same engagement. A host discovered by one member is already there for the others, along with its services, findings, credentials and loot — no export, no import, no “send me your scan”. The workspace database on that host is the single copy.

Buying seats

1. On Pricing, choose how many seats you need. One subscription covers the whole team and is billed per seat.
2. You get the first seat automatically — the account that pays is a member too.
3. Adding or removing seats later changes the same subscription; you are never asked to buy a second one.

Reducing the seat count never removes anyone. It only stops new invitations until the team fits again — who leaves is your decision, not the billing system's.

Inviting your team

1. Open your account → Team and enter the addresses.
2. Each person gets an invite link. Opening it activates the seat on their own Lupus login — they can create the account at that point if they don't have one.
3. Invites are single use, and an invitation holds its seat until it is claimed or you remove it.

Someone who already pays for Pro personally keeps their own plan; their seat is held and takes over automatically when the personal one ends. Nobody pays twice for the same month.

Connecting each phone

1. Start the agent in enrollment mode with room for your team: --enrollment-mode --enrollment-slots 5.
2. The agent prints an enrollment code. Each member enters it once, from their own phone, exactly as in remote mode — a fresh code is shown for the next device.
3. Need to add someone later? Send the agent process SIGHUP (kill -HUP <pid>) and it re-opens for one more device. No restart, so nobody's session drops.

Every device gets its own certificate and token, so enrolling a new phone never signs the others out, and each one can be revoked on its own.

Removing someone

Removing a member frees the seat immediately, so you can invite a replacement right away. The person keeps Pro until the end of the period you already paid for — you are not refunded for the remainder, and they are not cut off mid-engagement.

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.

Your own modules & payload files Pro

Metasploit ships thousands of modules, but sooner or later you write your own — or you want a payload built around a template the target's antivirus does not already know. Upload them once on the website and your phone installs them by itself.

Upload from your computer

Go to My arsenal in your account. Drop in .rb or .py files and they become Metasploit modules; anything else — an .exe to use as an msfvenom template, raw shellcode, a loader you compiled — is stored as a file you can pick on the device. Up to 20 MB per file, 50 MB per account.

Files that are not module source are encrypted in your browser before they are uploaded, so the storage provider only ever holds opaque bytes. The key belongs to your account, so this is not secrecy from us — it keeps your payloads away from third-party scanners.

The phone syncs by itself

There is no screen to visit and nothing to press. Whenever the app is open, online and connected to an agent, it checks whether your arsenal changed and installs what is new. You get a notification only when it actually installed something — or when something failed.

Your modules then appear in the ordinary Exploits, Auxiliary and Payloads browsers, alongside the stock ones, with your account name in the path so they are easy to spot. Configure and run them exactly like any other module.

Using your own msfvenom template

In Msfvenom, tap the folder button next to Template. It opens already showing the files you uploaded — no path to type — plus a shortcut to Metasploit's own bundled templates if you would rather start from one of those.

When a module does not show up

Check the My arsenal page. Every file carries the result your device reported: if Metasploit refused to load a module, the Ruby error is right there under it — usually a syntax error or a missing require. Fix the file, upload it again, and the next sync replaces it.

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.

Keeping Lupus off the network you're testing

During an engagement your phone is usually joined to the client's Wi-Fi, and that is a poor place for Lupus' own traffic to leave from — for two separate reasons. Whoever runs that network can see it, and it frequently has no real way out anyway: a captive portal, a filtered uplink, an isolated lab segment.

Settings → Global → Network sends Lupus' own traffic — the AI, and the account API the AI depends on — over mobile data, while the phone stays associated to the Wi-Fi. The engagement itself does not move: your scans keep running on the network you are testing.

What moves and what doesn't

• Moves to mobile data: the AI agent's conversation with the model, and the account calls behind it — entitlement, the AI session, telemetry.
• Stays on the Wi-Fi: everything that is the engagement. Nmap, Nuclei, Metasploit, sessions, the agent connection, and anything aimed at a private address. Your targets are on that network; the traffic that reaches them has to stay there.
• Never moves: the big downloads — the on-device tool set, app updates and Nuclei templates. Those are hundreds of megabytes and stay on the default network so they cannot quietly eat a data plan.

Settings

Settings has three sections down the left side:

• Global — the agent connection status, an Execute as root toggle, the Network block that decides whether Lupus' own traffic leaves over mobile data, on-device tool updates and your account.
• 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 uploaded a module and it does not show up

Open My arsenal and look at the file's status. The sync only runs while the app is open, online and connected to an agent, so it may simply not have run yet. If it says failed, the Ruby error from Metasploit is shown underneath — fix the file and upload it again.

My arsenal says the quota is full

An account holds 50 MB, with a 20 MB ceiling per file. Delete something you are not using; the next sync removes it from your device too.

The AI stopped working after I set Network to Always

Always refuses to use the Wi-Fi, so if there is no mobile data connection nothing gets through — that is deliberate, not a bug. The status line under Settings → Global → Network says which it is: check that mobile data is switched on and a SIM is present, or move to Auto, which only uses mobile data when the Wi-Fi has no internet.

My scans broke while Lupus was on mobile data

They shouldn't — scans, Metasploit and anything aimed at a private address deliberately stay on the Wi-Fi. What does break them is Android deciding the Wi-Fi has no internet and routing around it entirely; the Network block warns you when that happens. Reconnect to the Wi-Fi, or accept its “stay connected” prompt, and the local network comes back.

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.