Command line reference

The basics

The same program is the guard, the app window and the command line. On Windows the installed command is C:\Program Files\Defendingo\defendingo.exe; on Linux it is defendingo (a link in /usr/local/bin to /opt/defendingo/defendingo). The examples below write defendingo for short. defendingo --help lists every command, and defendingo <command> --help shows its flags and examples.

Where the answers come from

source: "guard"

The guard is running. Commands ask its local API on 127.0.0.1:34646, only reachable from this computer. Live and complete; on Windows with the installed guard, kernel events catch connections that last a split second.

source: "history_file"

The guard is not running but history exists. apps, history, check, explain and export read the history file directly, read-only.

source: "snapshot"

The guard is not running and the question is live. now and run take quick snapshots of the socket tables instead; very short connections can be missed.

Start the guard with defendingo ui or by opening the Defendingo app. On Linux with the system service: sudo systemctl start defendingo.

Exit codes

0

Fine. For check and run: nothing to worry about.

1

Error: a bad argument, or something could not be read. With --json the error is printed as {"ok": false, "error": "...", "exit_code": 1}.

2

The guard is not running. status always exits 2 in that case (the answer is still printed). Other commands exit 2 only when there is no history to fall back on.

3

check found something to look at; run saw a connection with a warning.

Time arguments

--since and --until accept a duration that long ago (30s, 15m, 2h, 7d, 1w), the words today, yesterday and now, a unix time (1793354214), a date (2026-10-30) or a date and time in local time ("2026-10-30 14:05"). The default window is the last 24 hours. History is kept for 90 days.

Risk levels

risk is a number from 0 to 4 and risk_label the word: ok (0), info (1), notice (2), warning (3), high (4). --min-risk LEVEL filters on it, and --flagged is short for --min-risk notice. A warning means "have a look", not "you are hacked".

Windows and Linux: who needs administrator rights

Reading the history and asking the running guard needs no special rights on either system. defendingo packets captures packets and needs an administrator terminal on Windows or sudo on Linux. Without the guard, a plain defendingo scan on Linux shows your own programs in full; sudo defendingo shows every program. install and uninstall change the automatic start and need administrator rights or sudo too. run never gives the program it starts any extra rights.

Commands

defendingo status

Is the guard running, how does it record, what is happening right now, today's counts. Flags: --json, --no-color. Exit code 2 when the guard is not running.

$ defendingo status
Defendingo status
The guard is running (version 0.9.0, full recording (kernel events)). Right now: 23 open connections from 9 programs. Today: 312 connections from 41 programs, 57 new places, 2 with a warning.
  Admin rights: yes   Kernel events: yes   Recording: Kernel events + polling: every connection is recorded
  Running since: 2026-10-30 08:02 (6 h ago)
  Starts at logon: yes   Auto-update: yes   Updates: up-to-date You have the newest version.
  Dashboard: http://127.0.0.1:34646   History file: C:\Users\you\AppData\Local\Defendingo\history.db

$ defendingo status --json
{
  "ok": true,
  "guard_running": true,
  "source": "guard",
  "version": "0.9.0",
  "platform": "windows",
  "dashboard": "http://127.0.0.1:34646",
  "history_file": "C:\\Users\\you\\AppData\\Local\\Defendingo\\history.db",
  "guard": {
    "version": "0.9.0", "platform": "windows", "admin": true, "kernel_events": true,
    "capture_note": "Kernel events + polling: every connection is recorded",
    "started": 1793340120, "open_now": 23, "apps_now": 9, "autostart": true, "auto_update": true,
    "update": { "state": "up-to-date", "latest": "0.9.0", "detail": "You have the newest version." }
  },
  "today": { "flows_today": 312, "apps_today": 41, "new_today": 57, "alerts_today": 2, "total_flows": 12345, "oldest_day": "2026-08-01" },
  "summary": "The guard is running (version 0.9.0, full recording (kernel events)). Right now: 23 open connections from 9 programs. Today: 312 connections from 41 programs, 57 new places, 2 with a warning."
}

defendingo now (aliases: connections, live)

What is happening right now. With the guard: its live feed, newest first, each connection recorded the moment it appeared, with first_ever marking the first time that program ever talked to that place. Without the guard: a one-time snapshot of the open sockets.

defendingo now
defendingo now --flagged           # only connections with a warning
defendingo now --json --limit 50

--flagged

Only connections with at least a NOTICE warning.

--limit N

Most connections to list (default 100, max 400).

--json, --no-color

JSON output; plain text without colors.

The answer is a connection list: { "ok": true, "source": "guard", "count": 1, "items": [ ...connections... ], "note": "The guard's live feed: the newest connections first, each recorded the moment it appeared." }. See the connection object.

defendingo apps

Programs that used the network in a time window, worst warning first.

defendingo apps                        # the last 24 hours
defendingo apps --since 7d --flagged   # only programs with a warning this week
defendingo apps --json --limit 20

--since TIME, --until TIME

The time window (default: the last 24 hours).

--flagged

Only programs with at least a NOTICE warning.

--limit N

Most programs to list (default 100, max 500).

--json, --no-color

JSON output; plain text without colors.

{
  "ok": true,
  "source": "guard",
  "window": { "since": 1793275000, "until": 0 },
  "count": 2,
  "items": [
    { "app": "SomeGame.exe", "path": "C:\\Users\\you\\Downloads\\SomeGame.exe", "signature": "UNSIGNED", "signer": null,
      "connections": 4, "destinations": 3, "hits": 9, "max_risk": 4, "risk_label": "high", "last_seen": 1793352081,
      "categories": ["Unknown", "Cloud hosting"] },
    { "app": "Discord.exe", "path": "C:\\Users\\you\\AppData\\Local\\Discord\\app-1.0.9200\\Discord.exe", "signature": "signed", "signer": "Discord Inc.",
      "connections": 12, "destinations": 7, "hits": 140, "max_risk": 0, "risk_label": "ok", "last_seen": 1793352000,
      "categories": ["Gaming/launcher"] }
  ]
}

connections counts distinct destination, port and direction per day; destinations counts distinct remote addresses; hits adds up every sighting. signature is one of signed, UNSIGNED, untrusted-sig, BAD-SIG, system or ? (file not visible; run as administrator). On Linux, "signed" means installed by the package manager and unchanged since.

defendingo history

Search up to 90 days of recorded connections by program, host, port, protocol, direction, category, time and risk. Newest first.

defendingo history --app Discord.exe --since 2h
defendingo history --match pastebin --since 30d
defendingo history --port 22 --proto TCP --direction outgoing
defendingo history --category Unknown --flagged --since today --json
defendingo history --since "2026-10-29 08:00" --until "2026-10-29 18:00" --limit 500

--app NAME

Exact program file name (case does not matter).

--match TEXT, -m, --host

Free text: host, IP address, owner, program, path or category contains this.

--port N

Remote or local port.

--proto TCP|UDP

Protocol.

--direction DIR

outgoing, incoming or listening.

--category NAME

Exact category: This PC, Local network, Microsoft/Windows (Linux: Linux system), Gaming/launcher, Browser, CDN/proxy, Cloud hosting, Known service, Unknown.

--min-risk LEVEL, --flagged

Lowest warning level to include: info, notice, warning, high.

--since TIME, --until TIME

The time window (default: the last 24 hours).

--limit N, --offset N

Paging: at most N rows (default 100, max 500), skipping the first N.

Answer: { "ok": true, "source": ..., "window": {...}, "count": N, "items": [ ...connections... ], "note": "..." }.

defendingo check (alias: warnings)

Things worth a look: every warning in the window, grouped by program and warning code, with the warning in plain words, what it means and what to check. Exit code 3 when there is anything, 0 when there is not, which makes it a one-line health check for scripts and schedulers.

defendingo check                           # the last 24 hours
defendingo check --since 7d --min-risk warning
defendingo check --json && echo "all clear"

--min-risk LEVEL

Lowest level to report: info, notice (default), warning, high.

--since TIME, --until TIME

The time window (default: the last 24 hours).

--limit N

Most items to list (default 50, max 500).

{
  "ok": true,
  "source": "guard",
  "window": { "since": 1793275000, "until": 0 },
  "min_risk": 2,
  "count": 1,
  "items": [
    {
      "app": "SomeGame.exe",
      "path": "C:\\Users\\you\\Downloads\\SomeGame.exe",
      "signature": "UNSIGNED",
      "signer": null,
      "code": "RISKY_LOCATION",
      "severity": "high",
      "risk": 4,
      "detail": "SomeGame.exe runs straight from the Downloads folder",
      "what_it_means": "Runs from Downloads, Temp, Public or AppData. HIGH if it is also unsigned.",
      "what_to_check": "Programs you installed usually live in Program Files. Open the folder and check what the file is.",
      "connections": 4,
      "places": ["api.example-game.net", "Cloudflare", "203.0.113.9"],
      "first_seen": 1793350000,
      "last_seen": 1793352081
    }
  ],
  "summary": "1 thing to check, from 1 program: SomeGame.exe (RISKY_LOCATION)."
}

defendingo explain [TARGET]

Who or what something is: an IP address, a host name, a program, a warning code or a category, with what the history shows about it. Without a target it prints the whole glossary of categories and warning flags.

defendingo explain                       # glossary
defendingo explain 162.159.134.234       # an address: owner, category, which programs talked to it
defendingo explain api.telegram.org      # a name: known service, or a malware indicator?
defendingo explain SomeGame.exe --json   # a program: signature, places, warnings from the history
defendingo explain UNSIGNED_ONLINE       # a warning code: what it means, what to check
defendingo explain "Cloud hosting"       # a category

{
  "ok": true,
  "query": "api.telegram.org",
  "kind": "host",
  "source": "guard",
  "warning": { "provider": "api.telegram.org", "category": "warning", "note": "Telegram bot API - often used by stealers to send stolen data" },
  "history": {
    "connections": 3,
    "apps": [ { "app": "updater.exe", "signature": "UNSIGNED", "connections": 3, "last_seen": 1793352081 } ],
    "places": ["api.telegram.org"],
    "categories": ["Unknown"],
    "max_risk": 3,
    "risk_label": "warning",
    "flags": ["BAD_INDICATOR", "UNSIGNED_ONLINE"],
    "first_seen": 1793300000,
    "last_seen": 1793352081
  },
  "summary": "api.telegram.org is not in any list Defendingo knows (category Unknown). That is not automatically bad: look at which program talks to it. Warning (warning): Telegram bot API - often used by stealers to send stolen data. In the last 90 days 1 program talked to it: updater.exe (3 connections). Worst warning: warning (BAD_INDICATOR, UNSIGNED_ONLINE)."
}

kind is ip, host, program, flag, category or glossary. known (owner and category, when the address or name is in Defendingo's lists), warning, program (path, signature, signer) and history appear when there is something to say; glossary holds entries for flags and categories (name, severity, meaning, what_to_check).

defendingo run PROGRAM [ARGS...]

"Run with Defendingo" from the terminal: starts the program with your normal rights, follows it and every helper it starts, prints each connection as it happens and ends with a summary. Stops early when the program and everything it started have ended, otherwise after --seconds. The program is never run as administrator, never stopped and never changed. Exit code 3 when a connection had a warning.

defendingo run "C:\Games\SomeGame.exe"
defendingo run --seconds 60 --json /opt/tool/tool -- --flag value
defendingo run --seconds 60 "C:\Users\you\Downloads\installer.exe"   # test-drive a download before trusting it

PROGRAM

The full path of the program to start. Everything after it is passed to the program as arguments.

--seconds N

Watch for at most this long (default 30); stops earlier when the program ends.

--json, --no-color

One JSON report at the end instead of the live log; plain text without colors.

{
  "ok": true,
  "program": "C:\\Games\\SomeGame.exe",
  "pid": 21080,
  "source": "guard",
  "seconds_watched": 30.0,
  "exited": false,
  "note": "Time is up after 30 s; the program is still running.",
  "processes": [ { "pid": 21080, "ppid": 4120, "name": "SomeGame.exe", "path": "C:\\Games\\SomeGame.exe", "started": 1793352000, "exited": null } ],
  "connections": [ ...connections... ],
  "places": ["api.example-game.net", "Cloudflare"],
  "categories": { "Unknown": 1, "CDN/proxy": 2 },
  "warnings": [ ...connections with flags... ],
  "summary": "SomeGame.exe was watched for 30 s. It talked to 2 places: api.example-game.net, Cloudflare. 1 connection with a warning: UNSIGNED_ONLINE. Time is up after 30 s; the program is still running."
}

defendingo export

Recorded connections as CSV or JSON, to a file or to standard output. Same text, program and risk filters as history.

defendingo export --since 7d --out week.csv
defendingo export --format json --app chrome.exe --since 1d
defendingo export --flagged --since 30d --out warnings.csv

--format csv|json

Default: from the file name's extension, else CSV.

--out FILE

Write here instead of standard output.

--app NAME, --match TEXT, --min-risk LEVEL, --flagged

The same filters as history.

--since TIME, --until TIME

The time window (default: the last 24 hours).

--limit N, --offset N

At most 500 rows per call (the default); use --offset for the next page.

CSV columns: first_seen, last_seen, app, pid, path, signature, signer, proto, direction, local_port, remote_addr, remote_port, host, provider, category, risk, risk_label, flags, reason, hits. flags is CODE(severity): detail; CODE(severity): detail. The JSON form is an array of connection objects.

defendingo packets

Packet capture per process from the terminal: every packet for a few seconds, in plain words, matched to the program that sent it. Needs administrator or root rights. The same filter language, recording and analysis as Developer mode on the Packets page; the Packets guide has more examples.

defendingo packets --seconds 10
defendingo packets --seconds 5 --json --limit 100                              # summary per program and place, plus a sample
defendingo packets --seconds 30 --filter "tcp.port == 443 and app contains chrome" --write session.pcapng
defendingo packets --read session.pcapng --stats
defendingo packets --read session.pcapng --follow first

--seconds N

How long to capture (default 10).

--filter EXPR

Keep only matching packets, in the display filter language, e.g. "dns or tls.sni contains github".

--write FILE

Save whole packets to a .pcapng file that opens in Wireshark; a comment on each packet names its program and PID. A bare file name goes to the recordings folder under Defendingo's data folder; give a full path to save elsewhere.

--max-mb N

Size cap for --write in MB (default 1024); capture stops when it is reached.

--read FILE

Read a .pcap or .pcapng file instead of capturing.

--stats

Conversations, endpoints, programs and the protocol hierarchy instead of every packet.

--follow STREAM

Show one conversation's contents: a number from --stats, first, or tcp:local:port:remote:port.

--limit N

With plain --json: most places and sample packets to include (default 50, max 1000).

--json

Plain capture: totals, the places with the most traffic (places), bytes per program (apps) and a short sample. With --filter, --read or --write: one JSON object per packet. With --stats or --follow: one object.

$ defendingo packets --seconds 5 --filter "dns" --json
{"seq":418,"at":1793355201.412,"dir":"out","proto":"UDP","kind":"DNS","local":"192.168.1.20","local_port":58213,"remote":"1.1.1.1","remote_port":53,"len":74,"payload":32,"flags":"","info":"Looks up api.github.com","host":"one.one.one.one","pid":6548,"app":"chrome.exe"}
{"seq":419,"at":1793355201.431,"dir":"in","proto":"UDP","kind":"DNS","local":"192.168.1.20","local_port":58213,"remote":"1.1.1.1","remote_port":53,"len":106,"payload":64,"flags":"","info":"api.github.com is 140.82.121.6","host":"one.one.one.one","pid":6548,"app":"chrome.exe"}

Contents of secure connections stay encrypted; names come from DNS, the TLS server name and plain HTTP. No payloads are included in the JSON summary.

defendingo mcp [--print-config]

The server for AI assistants, over standard input and output. Clients start it for you; --print-config prints ready-to-paste settings for Claude Desktop, Claude Code, Cursor and VS Code with the real installed path. The tools and setup are on the MCP page.

defendingo mcp --print-config
defendingo mcp                  # the server itself

defendingo scan (the default command)

One snapshot of all connections and open ports as a table, the way you would otherwise combine netstat, Task Manager and a signature check by hand. Running defendingo with no command does the same.

defendingo                 # one snapshot
defendingo --flagged       # only rows with a warning
defendingo --all           # also this-PC-only (loopback) and closed sockets
defendingo --csv my.csv    # save as CSV (opens in a spreadsheet)
defendingo --json -        # print JSON only, for scripts

--flagged

Only rows with a NOTICE or higher warning.

--all

Also show loopback and already-closed sockets.

--json [FILE], --csv [FILE]

Save the results. Without a file name they go to the reports folder under Defendingo's data folder; - prints only the data to standard output.

--no-rdns

No reverse DNS lookups (sends no DNS queries at all).

--no-color

Plain text without colors.

Scan records have a slightly different shape from the connection object: time, proto, direction, state, local_addr, local_port, remote_addr, remote_port, dns_names, reverse_dns, provider, category, reason, pid, process, path, parent_pid, parent, signature, signer, risk, flags.

defendingo watch

Keep watching and print every new connection as it appears, with a JSON Lines log by default. Ctrl+C stops it.

defendingo watch                     # live: every new connection
defendingo watch --show-closed       # also print when connections close
defendingo watch --processes         # also print every new process that starts
defendingo watch --duration 600 --csv   # stop after 10 minutes, also log to CSV

--interval SECONDS

Seconds between checks (default 2).

--duration SECONDS

Stop automatically after this long.

--show-closed

Also print connections when they close.

--processes

Print every new process that starts, even without network activity.

--log FILE, --no-log

Where the JSON Lines log goes (default: the logs folder under Defendingo's data folder), or no log file.

--csv [FILE]

Also log new connections to a CSV file.

--all, --no-rdns, --no-color

As for scan.

Maintenance commands

defendingo ui

Open the dashboard in your browser; starts the guard if it isn't running.

defendingo agent

Run the guard in this window, to see what it does.

defendingo install

Start the guard automatically at every logon and add the "Run with Defendingo" menu entry (administrator terminal or sudo). The app does this on first launch.

defendingo uninstall

Remove the automatic start and the menu entries. Your history is kept.

defendingo update

Update now; the guard also does this by itself. --check only looks for a newer version. --disable-auto and --enable-auto switch the automatic update.

defendingo update-ranges

Download the latest official address lists (Cloudflare, AWS, Google, Fastly) right now; the guard refreshes them weekly by itself.

defendingo stats [--on|--off]

Show or change whether anonymous statistics are shared.

defendingo community [--on|--off]

Show or change community protection (off until you say yes).

The connection object

Returned by now, history, run and export --format json, whatever the source.

app

Program file name, e.g. Discord.exe; pid 1234 when the program could not be named.

pid

Process id at the time.

path

Full path of the program file, or null.

signature

signed, UNSIGNED, untrusted-sig, BAD-SIG, system or ?.

signer

Who signed it, e.g. Microsoft Corporation, or null.

proto

TCP or UDP.

direction

outgoing, incoming, listening (snapshots also use udp for open UDP ports).

local_port

0 for outgoing connections (their local port is random).

remote_addr, remote_port

The other side. Empty address for listening ports.

host

Name the program looked up for the address (from the DNS cache), else its reverse name, or null.

provider

Company or service behind the address: Steam, AWS, Riot Games via Cloudflare, or null.

category, reason

The category (see explain) and why, in plain words.

risk, risk_label

0 ok, 1 info, 2 notice, 3 warning, 4 high (the worst flag), and the word for it.

flags

Array of { "code", "severity", "detail" }. Codes: BAD_SIGNATURE, UNSIGNED_ONLINE, UNSIGNED_LISTENER, RISKY_LOCATION, BAD_INDICATOR, DISCORD_FROM_OTHER_APP, RAW_IP, SUSPICIOUS_PORT, UNTRUSTED_SIGNATURE, NO_PATH, NEW_PROCESS.

first_seen, last_seen

Unix seconds. History rows add up one program, destination and day.

hits

How many times it was seen.

first_ever

Live feed only: true the first time this program ever talked to this place.

{
  "app": "SomeGame.exe",
  "pid": 6548,
  "path": "C:\\Users\\you\\Downloads\\SomeGame.exe",
  "signature": "UNSIGNED",
  "signer": null,
  "proto": "TCP",
  "direction": "outgoing",
  "local_port": 0,
  "remote_addr": "188.114.96.3",
  "remote_port": 443,
  "host": "api.example-game.net",
  "provider": "Cloudflare",
  "category": "CDN/proxy",
  "reason": "address belongs to a CDN/proxy (hides the real server behind it)",
  "risk": 4,
  "risk_label": "high",
  "flags": [
    { "code": "UNSIGNED_ONLINE", "severity": "warning", "detail": "SomeGame.exe is not digitally signed and talks to the internet" },
    { "code": "RISKY_LOCATION", "severity": "high", "detail": "SomeGame.exe runs straight from the Downloads folder" }
  ],
  "first_seen": 1793352001,
  "last_seen": 1793352081,
  "hits": 3,
  "first_ever": true
}

Recipes

# Anything to worry about since yesterday? (exit code 3 means yes)
defendingo check --since yesterday

# Which programs talk to servers nobody can name?
defendingo history --category Unknown --since 7d --json | jq '[.items[].app] | unique'

# Everything a program did this week, as a spreadsheet
defendingo export --app SomeGame.exe --since 7d --out somegame.csv

# A nightly report
defendingo apps --since 1d --json > apps-$(date +%F).json

# Which servers did a game contact while I played? (administrator or sudo)
defendingo packets --seconds 60 --filter "app contains game" --write game.pcapng

Stability

Field names on this page are stable: new fields may be added, existing ones keep their names and types. Text output is for people and may change wording between versions; scripts should use --json. The same fields come back from the MCP tools, so an assistant and a script see the same data.