Skip to content

AGENTS.md — Talk to your MySecutec data through the CLI

This file tells an AI agent (Claude Code, Cursor, Copilot, a custom agent, etc.) how to use the mysecutec CLI to answer questions about a user's security posture. The CLI is the agent's tool; this document is its manual.

For the agent: You answer questions about assets, threats, leaked credentials, dark-net exposure, and security-module KPIs by running mysecutec commands and reading their JSON output. You never invent data — every figure you report must come from a command you actually ran.

Golden rules

  1. Always pass -o json. Text output is for humans and is truncated/aligned for terminals. JSON is stable, complete, and parseable. Use it for every command, then summarize for the user in prose.
  2. Never fabricate. If a command returns no data or errors, say so. Do not guess IDs, counts, severities, or dates.
  3. Read before you write. list/get/kpis/filter commands are safe and read-only. update, delete, and restore change customer data — see Mutations. Get explicit user confirmation first.
  4. Discover filters before filtering. Many modules expose a filter subcommand (assets filter, threats filter) that returns the exact accepted values and live counts. Use it instead of guessing.
  5. Confirm the context. Run mysecutec status to see the active environment and whether an organization is being impersonated. Data is scoped to that context.

Setup the agent can assume

The user authenticates themselves — the agent does not run login (it opens a browser for OAuth2). Verify the session instead:

1
mysecutec status -o json

If this shows an expired token, tell the user to run mysecutec login. Do not attempt to log in on their behalf.

Staying current

The CLI self-updates. If a command warns that a new version is available, or that this version is no longer supported, run mysecutec update (or tell the user to). mysecutec update --check reports availability without installing. The binary targets the environment baked in at install time (production, staging, or testing) and updates from that environment's host.

Global flags (valid on every command)

Flag Meaning
-o, --output json Use this always. json or text.
-e, --env <name> Target testing, staging, or production. Defaults to the configured environment.
-v, --verbose Print raw HTTP request/response — use only when debugging an error.
--no-color Disable ANSI color (harmless with -o json).

Context: environment and impersonation

1
2
3
4
5
mysecutec status -o json          # active env + auth + impersonation state
mysecutec config list             # persisted defaults (env, limit, output)
mysecutec orgs list --search acme # find an org to impersonate (note: --per-page, not --limit)
mysecutec impersonate <org_id>    # view another org's data (partner/admin)
mysecutec impersonate clear       # stop impersonating

Impersonation is stateful and persists between commands. If the user asks about "Acme Corp", impersonate that org first, run the queries, then offer to impersonate clear when done. Always tell the user which org's data you are reporting on.

The data commands

All modules follow the same shape: a noun, a verb, JSON out. Pagination is --limit / --offset everywhere except orgs list, which uses --per-page.

Assets — the inventory

1
2
3
4
5
6
7
mysecutec assets list -o json --limit 20 [--offset N]
mysecutec assets list -o json --search "secutec.com"
mysecutec assets list -o json --type domain --public-facing
mysecutec assets list -o json --module XDR --sort -business_value
mysecutec assets filter -o json                 # valid types/modules/sort fields
mysecutec assets get <asset_id> -o json
mysecutec assets threats <asset_id> -o json     # threats on one asset

List responses include pagination (total, offset, limit, next). To report a true total, read pagination.total — do not count the returned page. To enumerate everything, follow pagination.next / increment --offset.

Threats — the findings

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
mysecutec threats list -o json --limit 20
mysecutec threats list -o json --severity critical --status unsolved
mysecutec threats list -o json --first-seen-from 2026-01-01 --first-seen-to 2026-06-30
mysecutec threats list -o json --asset-id <asset_id>
mysecutec threats list -o json --related-to-asset-id <asset_id> --breach-category exposed
mysecutec threats list -o json --updated-from 2026-01-01 --updated-to 2026-06-30
mysecutec threats filter -o json                # valid statuses/severities + counts
mysecutec threats get <threat_id> -o json
mysecutec threats logs <threat_id> -o json      # audit trail
mysecutec threats aggregate --group-by severity --module asm -o json   # generic server-side aggregation

threats filter returns statuses, severities, etc. with filtered_total counts — use it to answer "how many critical threats?" without paging.

threats aggregate is the generic counting engine behind the dashboards: pass --group-by path[:alias] (repeatable), --module <license_module>, and --filter path=v1,v2. It's the most efficient way to answer "break down X by Y" questions.

Security modules (mostly read-only KPIs)

Each module exposes some of: kpis (current snapshot), years (data years available), year-kpis --year YYYY, plus module-specific list commands.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
# Extended Detection & Response
mysecutec xdr kpis -o json
mysecutec xdr agents -o json --limit 50
mysecutec xdr threats -o json --search <q>
mysecutec xdr year-kpis --year 2025 -o json

# Leaked Credential Management
mysecutec lcm kpis -o json
mysecutec lcm breaches -o json          # grouped by breach source
mysecutec lcm breaches-overview -o json # exfiltrated vs exposed
mysecutec lcm categories -o json
mysecutec lcm leaks -o json             # combolist/phished/scraped/unknown
mysecutec lcm stealers -o json          # infostealer sources

# Dark Net Monitoring
mysecutec dnm overview -o json
mysecutec dnm blackmarket -o json
mysecutec dnm botnet -o json
mysecutec dnm pii -o json               # PII exposure — sensitive, see below
mysecutec dnm suspicious -o json
mysecutec dnm im -o json

# Secure DNS
mysecutec sdns kpis -o json
mysecutec sdns queries -o json          # blocked DNS queries
mysecutec sdns top-queries -o json
mysecutec sdns agents -o json           # registered SDNS agents
mysecutec sdns sites -o json            # configured sites

# Microsoft 365 (basic) and Microsoft Security Center (rich)
mysecutec m365 kpis -o json
mysecutec m365 admins -o json
mysecutec msc tenant <tenant_id> -o json          # tenant overview
mysecutec msc signins <tenant_id> -o json         # sign-in aggregates (--start/--end/--group-by)
mysecutec msc ca-policies <tenant_id> -o json     # conditional-access policy results
mysecutec msc licenses <tenant_id> -o json        # license inventory

# Attack Surface Mgmt / Advanced Threat Hunting / Third-Party Risk
mysecutec asm kpis -o json
mysecutec ath alerts -o json
mysecutec ath map -o json               # alert geography (source → destination)
mysecutec tprm kpis -o json
mysecutec tprm bitsight -o json         # Bitsight security ratings

# Identified Vulnerability Systems
mysecutec ivs kpis -o json
mysecutec ivs assets -o json
mysecutec ivs threats -o json
mysecutec ivs years -o json
mysecutec ivs year-kpis --year 2026 -o json

# Phishing Detection Kit
mysecutec pdk top-phishing-domains -o json

CSV export (asynchronous)

1
2
3
4
5
mysecutec export create --resource threats --columns id,name,severity   # start a CSV export
mysecutec export create-aggregate --resource threats --group-by severity # grouped CSV export
mysecutec export list -o json                                            # track export status
mysecutec export filter -o json
mysecutec export download <id> --output-file threats.csv                 # fetch the file

Exports are async: create returns an ID and a queued/processing status; poll export list until the record's download_available is true, then export download <id>.

Account & operations (IAM, reports, notifications)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
mysecutec iam members --org <org_id> -o json   # org members
mysecutec iam groups <user_id> -o json         # a user's groups
mysecutec orgs impersonation-tree -o json      # partner → client tree (IDs feed `impersonate`)

mysecutec report list -o json                  # report history
mysecutec report settings get -o json          # report settings (--scope user|tenant|users)
mysecutec report download <id> --output-file report.pdf

mysecutec notification inbox -o json           # uses --page/--page-size (NOT limit/offset)
mysecutec notification unread-count -o json
mysecutec notification settings get -o json
mysecutec notification devices list -o json

Discover years before requesting year-kpis:

1
mysecutec xdr years -o json   # -> {"data":{"items":[2026,2025]}}

Mutations require confirmation

These commands write to the customer's live data. Always show the user the exact command and the current value first, get a clear yes, then run it. All mutating commands accept -y/--yes to skip the interactive confirmation (use only when the user has already approved); without it they prompt.

Single-record: 

1
2
3
4
mysecutec assets update <asset_id> ...        # change asset metadata
mysecutec assets delete <asset_id>            # soft delete
mysecutec assets restore <asset_id>           # undo soft delete
mysecutec threats update <threat_id> ...      # change one threat's status/note

Bulk (up to 1000 IDs; IDs via args, repeated --id, or piped --stdin): 

1
2
3
4
5
6
7
8
9
# Bulk threat status — --user-status is required (unsolved|false_positive|accepted|solved)
mysecutec threats status <id1> <id2> --user-status accepted --note "Risk accepted"
mysecutec threats list --severity low -o json | jq -r '.threats[].id' \
  | mysecutec threats status --stdin --user-status false_positive --yes

# Bulk asset business value (1-5)
mysecutec assets business-value <id1> <id2> --value 5
mysecutec assets list --type domain -o json | jq -r '.assets[].id' \
  | mysecutec assets business-value --stdin --value 4 --yes

The bulk threat endpoint uses partial-success semantics: it reports how many succeeded vs failed (per-ID), so always surface the failed count to the user.

IAM, report, and notification settings commands also mutate (iam create-user, iam update-user, report settings set/delete, report generate, notification read, notification settings set/delete, notification devices remove) — same confirmation rules apply.

Run mysecutec <module> <verb> --help to see the exact flags before executing a mutation. Prefer reading the current state with get first so you can report what is about to change.

  1. mysecutec status -o json — confirm auth + which org/env you're in.
  2. If the question is about another org: orgs list --search … then impersonate <id>.
  3. For "how many / breakdown" questions: prefer a filter or kpis command (server-side aggregates) over paging through list.
  4. For specifics: list with the narrowest flags, then get <id> for detail.
  5. Parse JSON, summarize for the user, and cite the numbers you actually got (pagination.total, KPI fields, filter counts).
  6. If you impersonated, offer to impersonate clear.

Example: "How exposed are we — give me the headline numbers"

1
2
3
4
5
6
mysecutec status -o json
mysecutec assets list -o json --limit 1          # read pagination.total
mysecutec threats filter -o json                 # severity/status counts
mysecutec lcm kpis -o json                        # leaked credentials
mysecutec dnm overview -o json                    # dark-net exposure
mysecutec xdr kpis -o json                         # endpoint detections

Then report: total assets, threats by severity/status, leaked-credential count, dark-net findings, and XDR agent/detection counts — each value traced to one of the commands above.

Error handling

  • Auth/expiry errors → tell the user to run mysecutec login. Never log in for them.
  • unknown flag → you used the wrong pagination flag. Remember orgs list uses --per-page; everything else uses --limit/--offset. Re-check with --help.
  • Empty results → report "no data found for that query," don't invent any.
  • Unexpected HTTP error → re-run once with -v to capture the raw response, then surface the actual error message to the user.

Sensitive data

LCM (leaked credentials), DNM pii/im (personal info, intercepted content), and threat details can contain personal or confidential data. Report aggregate counts and summaries by default; reproduce raw records (emails, passwords, message contents) only when the user explicitly asks, and never write them to files or external services without being told to.