saw-web-target-configuration

name	saw-web-target-configuration
description	DEFAULT skill for creating Snyk API & Web targets. Use for all target creation requests unless the user explicitly mentions an API target, OpenAPI schema, Swagger spec, or Postman collection. Handles web application targets with login sequences, 2FA, logout detection, and extra hosts via playwright-cli (preferred) or Playwright MCP (fallback).

Web Target Configuration Skill (Snyk API & Web)

Configure web application targets for Snyk API & Web security scanning with authentication support. For API targets, use the saw-api-target-configuration skill instead.

Browser Automation — Detect Before Recording

Login sequences require a real browser. Detect availability in this order:

1. playwright-cli (preferred for coding agents with Shell access)

playwright-cli --version
# or: npx @playwright/cli --version

If missing, install (no repo clone required):

npm install -g @playwright/cli@latest
playwright-cli install-browser chromium

Or, when a clone of this repo is available:

./scripts/setup-playwright.sh

Use npx @playwright/cli instead of playwright-cli when the global binary is not on PATH.

2. Playwright MCP (fallback for MCP-only clients)

Check whether Playwright MCP tools are available (e.g. browser_navigate, browser_snapshot, browser_evaluate, browser_network_requests).

If missing, tell the user to install Playwright MCP:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Or install Playwright from the Cursor Marketplace.

3. Neither available

If neither path works and the user cannot install one:

1. Tell the user that login sequences (multi-step login, 2FA) require browser automation.
2. Offer to install playwright-cli (preferred) or Playwright MCP.
3. Only if the user declines or installation fails, fall back to form login (Step 4) for simple single-page login forms.

Never guess CSS/XPath selectors without browser inspection.

Target Type Check — Do This First

Before proceeding, determine whether this is an API target or a web target:

• If the user has provided an OpenAPI/Swagger schema (URL or file), a Postman collection, or explicitly said "API target" — stop and use the saw-api-target-configuration skill instead.
• Otherwise, treat it as a web target by default. If the user just says "add a target", "create a target", or provides a URL without further qualification, proceed here.

When you finish adding/configuring a target, always summarize it with a table, and include a link to the target on Snyk API & Web. Use the Snyk API & Web app URL https://plus.probely.app. Include a column if you added extra hosts or not and in case you did, which ones.

Multiple Targets — Subagent Strategy

When the user provides more than one target, launch a subagent per target.

Browser path	Subagent concurrency
playwright-cli	Subagents may run in parallel — each MUST use a globally unique session name: playwright-cli -s=<session>. Do NOT use the bare domain, since multiple targets can share one hostname (duplicate-URL flows, multiple accounts on one app) and would collide into a shared browser context. Use <domain>-<targetIndex> (e.g. app.example.com-1, app.example.com-2), appending the account/username when several targets share a domain.
Playwright MCP	Subagents must run one at a time — Playwright MCP uses a single shared browser instance

Each subagent prompt should be short — just the target details and an instruction to read the skill file:

Configure a Snyk API & Web web target:
- URL: <url>
- Name: <name or "auto" — if "auto", derive from the site's <title>>
- Labels: <["Label1", ...] or "default" — if "default", do NOT pass labels param>
- Username: <user>
- Password: <pass>
- 2FA TOTP seed: <seed or "none">
- Browser session name: <session> (playwright-cli only — a globally unique name such as `<domain>-<targetIndex>`, plus the account/username when targets share a domain; use with `playwright-cli -s=<session>` for ALL browser commands)

First read the skill file at <ABSOLUTE_PATH_TO_THIS_SKILL_FILE> and follow the full workflow.
Return a summary with: target ID, name, URL, login sequence status, logout detection status, extra hosts, Snyk API & Web link (https://plus.probely.app/targets/{targetId}).

After all subagents finish, compile summaries into one table.

Credentials Management — Recommended (Used by Default)

Use the credential manager for sensitive values (passwords, TOTP seeds, etc.) by default. Store values via probely_create_credential with is_sensitive=True and use the returned uri (e.g. credentials://xxxx) in the API. If the user explicitly declines, inline values are allowed.

Shared Credentials Across Multiple Targets

When configuring multiple targets that use the same credentials, the credential may already exist in the credential manager from a previous target. Since sensitive (obfuscated) values cannot be read back, the agent cannot verify whether it matches — this causes a new credential entry per target, polluting the credential manager.

Rule: When multiple targets share the same credential and it already exists with is_sensitive=True, prompt the user to deobfuscate it (update to is_sensitive=False via probely_update_credential) so it can be read back and reused across targets. Inform the user why deobfuscation is needed.

Workflow for shared credentials:

1. Create the credential normally with is_sensitive=True for the first target.
2. When a subsequent target needs the same credential, find the existing one via probely_list_credentials.
3. If the existing credential is sensitive (is_sensitive=True or value is null), prompt the user: "The credential '' is obfuscated. To reuse it across multiple targets, it needs to be deobfuscated. Would you like to proceed?"
4. If the user agrees, update it: probely_update_credential(credentialId, is_sensitive=False).
5. Reuse the same credential uri for the new target.

Pattern:

cred = probely_create_credential(
  name="<target_name> - <description>",
  value="the_actual_secret_value",
  is_sensitive=True
)
# cred["uri"] → "credentials://xxxx"

Credential URIs: Use the format credentials://<credential_id> (e.g., credentials://4DY4qGohso1r). Get credential URIs from probely_list_credentials or probely_create_credential. Do NOT use template syntax like {{cred-name}}.

Browser Session Isolation (playwright-cli only)

Each target MUST use a globally unique named session (-s=<session>) for fully isolated browser context (separate cookies, storage, network logs). Never reuse the bare <domain> as the session name: multiple targets can share a hostname (duplicate-URL flows, multiple accounts on one app), and colliding names make parallel subagents share one browser context. Build the name from the domain plus a discriminator, e.g. <domain>-<targetIndex> or <domain>-<username> (such as app.example.com-alice, app.example.com-bob).

Shell Timeout (playwright-cli only)

The Shell tool defaults to a 30-second timeout (block_until_ms: 30000), which is often too short for browser automation.

ALWAYS set block_until_ms: 60000 on Shell calls that run playwright-cli. For slow targets/pages, use block_until_ms: 90000.

Web Application Onboarding Workflow

Step 1: Gather Information and Determine Authentication Method

Ask the user for (or derive):

1. Target URL
2. Target name (User provided > site <title> > FQDN)
3. Labels (Only pass if specified by user, do not add "Agentic")
4. Login credentials
5. 2FA/MFA requirements

Authentication method (in order):

1. Login sequence via playwright-cli — preferred when Shell is available.
2. Login sequence via Playwright MCP — when CLI is unavailable but MCP browser tools exist.
3. Form login — fallback only when neither browser path is available.

Creating Duplicate Targets

To create a duplicate target (same URL as existing target), use allow_duplicate=True. This is useful when you want multiple targets for the same URL with different configurations (e.g., different authentication methods, different test scenarios):

probely_create_web_target(
    name="MyApp - Different Auth Method",
    url="https://app.example.com",
    allow_duplicate=True,
)

Reachability Failures

If target creation fails because the target is unreachable or the domain cannot be resolved, do not stop at the first error. Ask the user whether you should retry with skip_reachability_check=True. Only retry after the user explicitly agrees.

Step 2A: Record Login Sequence — playwright-cli (preferred)

Use playwright-cli via the Shell tool. Set block_until_ms: 60000 (or 90000 for slow pages).

1. Open session and navigate: playwright-cli -s=SESSION open <url>
2. Find the login page — use snapshot and goto.
3. Inspect form elements — run scripts/inspect-login-form.js via playwright-cli -s=SESSION eval '<js>'. Repeat on every login step. If it returns step: "canvas" (or a canvas field with submit: null), the fields/button are painted on a <canvas> (a canvas-rendered login, e.g. Flutter web) — read the page <script> or take a screenshot to find the field/button rectangles and use bclick/bfill_value with coordinates. See references/sequence-format.md → Canvas-Rendered Logins. If it returns step: "shadow_dom" (fields inside open shadow roots), use the inner-element selector it reports (e.g. input[type="password"]) with the attribute-based xpath it reports (a real XPath that pierces the shadow root, e.g. //input[@type='password']; /html/node/shadow is only a fallback) — never a host input piercing selector. Shadow roots are isolated scopes, so inner elements can share id/name/type: ensure each selector/XPath is unique across all shadow roots (heed any ambiguous/warning in the output). See references/sequence-format.md → Shadow DOM Inputs.
4. Fill credentials and submit — use snapshot to get element refs, then fill and click. Refs (e.g. e15) or unique CSS selectors both work. If clicking the login trigger opens a popup window (a new tab appears — e.g. from window.open(...)), switch to it with playwright-cli -s=SESSION tab-select <index> before inspecting/filling, and add "allow_popups": true to the first goto step of the sequence. See references/sequence-format.md → Popup-Based Logins.
5. Handle 2FA if needed — use probely_generate_totp for the live OTP, then fill the OTP field.
6. Verify login success — record the absolute post-login URL (eval '() => window.location.href').
7. Verify login selectors are absent post-login — use eval.
8. Detect external API hosts (CRITICAL) — read references/extra-hosts.md; run playwright-cli -s=SESSION requests at pre/post-login checkpoints.
9. Generate login sequence JSON — read references/sequence-format.md.
10. Close session — playwright-cli -s=SESSION close

Then apply SAW configuration (Step 3).

Step 2B: Record Login Sequence — Playwright MCP (fallback)

Use when playwright-cli is unavailable but Playwright MCP tools exist.

1. Navigate to target URL — browser_navigate
2. Find the login page and record the URL.
3. Inspect form elements — run scripts/inspect-login-form.js via browser_evaluate on every login step. If it returns step: "canvas" (or a canvas field with submit: null), the fields/button are painted on a <canvas> (a canvas-rendered login, e.g. Flutter web) — read the page <script> or take a screenshot to find the field/button rectangles and use bclick/bfill_value with coordinates. See references/sequence-format.md → Canvas-Rendered Logins. If it returns step: "shadow_dom" (fields inside open shadow roots), use the inner-element selector it reports (e.g. input[type="password"]) with the attribute-based xpath it reports (a real XPath that pierces the shadow root, e.g. //input[@type='password']; /html/node/shadow is only a fallback) — never a host input piercing selector. Shadow roots are isolated scopes, so inner elements can share id/name/type: ensure each selector/XPath is unique across all shadow roots (heed any ambiguous/warning in the output). See references/sequence-format.md → Shadow DOM Inputs.
4. Fill credentials and submit — record selectors for the sequence JSON. If the login opens in a popup window (a new page/tab from window.open(...)), switch to it (browser_tabs/select the new page) before inspecting/filling, and add "allow_popups": true to the first goto step of the sequence. See references/sequence-format.md → Popup-Based Logins.
5. Handle 2FA if needed — use probely_generate_totp for the live login.
6. Verify login success — record the absolute post-login URL for logout detection.
7. Verify login selectors are NOT on the post-login page — browser_evaluate.
8. Detect external API hosts (CRITICAL) — read references/extra-hosts.md; use browser_network_requests() at pre/post-login checkpoints.
9. Generate login sequence JSON — read references/sequence-format.md.

Then apply SAW configuration (Step 3).

Step 3: Apply SAW Configuration (both browser paths)

target = probely_create_web_target(
    name=..., url=..., desc=..., labels=...
)  # use target["id"] as targetId

# If 2FA: call probely_configure_2fa_totp BEFORE creating the sequence (use otp_code in sequence JSON)

probely_create_credential(...)  # password — link via custom_field_mappings

# The first "goto" step of the sequence content MUST include "powered_by": "saw mcp"
probely_create_sequence(
    targetId,
    name="Login Sequence",
    content="...",
    sequence_type="login",
    enabled=True,
    custom_field_mappings=[...],
)

probely_configure_sequence_login(targetId, enabled=True)

# See references/logout-detection.md
probely_configure_logout_detection(
    targetId,
    enabled=True,
    check_session_url=...,
    logout_detector_type=...,
    logout_detector_value=...,
    logout_condition=...,
)

# See references/extra-hosts.md
probely_create_extra_host(targetId, hostname="...", ip_address="")

Step 4: Form Login (no browser automation)