docs(connectors): document FOSSA scoping filters and Qualys tag grouping

docs/content/connectors/toolreference/fossa.md

@@ -17,5 +17,57 @@ A FOSSA **Full** API token.
 1. Enter `https://app.fossa.com/api` in the **Location** field.
 2. Enter your FOSSA Full API token in the **Secret** field.
 3. Optionally, set a **Minimum Severity** to limit which findings are imported.
+4. Optionally, narrow what the connector imports with **Issue Categories**, **Project Labels**, **Project Title Filter** and **Tags** (see below).
 
 Each FOSSA project becomes a Record. Only your organization's **active** issues are imported, covering both vulnerability and license-policy findings — so this connector can drive licence compliance work as well as security remediation.
+
+#### Scoping the import (optional)
+
+By default the connector discovers **every** project the token can see and imports **both** issue categories. In a large FOSSA organization that can mean hundreds of Records and a lot of licensing findings a security team may not want, or the reverse. The fields below, under **Import Filters** on the connector form, control the finding volume and which FOSSA projects become assets. All of them can be changed after the connection is created.
+
+##### Issue Categories
+
+Choose which FOSSA issue categories to import: **Vulnerabilities**, **Licensing**, or both (the default). At least one must stay selected.
+
+An unselected category is not downloaded at all, so a vulnerabilities-only connection also syncs faster. Use this when licence compliance is handled elsewhere, or when you want a separate connection per team.
+
+##### Project Labels
+
+Import only FOSSA projects that carry **any** of the labels you list, as a comma-separated list of FOSSA project label names:
+
+```
+prod, payments
+```
+
+* Labels are matched as **whole names**, exactly but **case-insensitively**, so `prod` matches a label `Prod` but not `production`.
+* A project with **no labels** is excluded whenever this field is set. If your FOSSA projects are not labelled, setting this field excludes every project.
+* Leave it blank to import every project.
+
+##### Project Title Filter
+
+Import only FOSSA projects whose **title** matches **any** of the patterns you list. A project with no title is matched on its FOSSA locator instead.
+
+```
+github.com/example/*, *-service
+```
+
+The example above imports every project under `github.com/example/` plus every project whose title ends in `-service`.
+
+* Matching is **case-insensitive**.
+* `*` matches any run of characters, **including `/`**, so `*web` matches `github.com/example/web`.
+* `?` matches exactly one character, and `[...]` matches one character from a set or range, for example `api-v[12]`.
+* Commas separate patterns, so a pattern cannot contain one. To match a literal comma, use `?` in its place.
+* A malformed pattern (for example an unclosed `[`) makes the connector fail with a configuration error, rather than silently matching nothing on every Sync.
+* Leave it blank to import every project.
+
+When **Project Labels** and **Project Title Filter** are both set, a project must pass **both**: it needs one of the labels **and** a matching title.
+
+##### Tags
+
+The **Tags** field imports only findings that carry at least one of the tags you list. Every FOSSA finding is tagged with its category, so `category:vulnerability` or `category:licensing` works here, as does the FOSSA issue type (for example `fossa:policy_conflict`) and the dependency's package manager (for example `package-manager:npm`). Prefer **Issue Categories** to split by category: it skips the download entirely instead of filtering after it.
+
+##### Changing the scope later
+
+* A project that a newly narrowed project filter excludes is no longer discovered. Its existing Record follows the normal lifecycle for assets the tool stops reporting: a **mapped** Record is flagged `MISSING`, and an unmapped `NEW` Record is removed. A Sync that runs before discovery catches up skips the Record rather than importing an empty result, so its findings are not closed by accident.
+* **Turning off an issue category closes its findings** in projects that still have findings in the other category. Both categories are imported into the same test, so the next Sync's reimport closes the findings it no longer sees. A project whose findings were **all** in the category you turned off syncs empty. On DefectDojo-hosted instances, and on installs from the DefectDojo Helm chart or Docker Compose files, the connectors service runs with chunked sync on (`DD_CONNECTORS_CHUNKED_SYNC=true`), so an empty sync skips the close step and those findings stay open; close or delete them in DefectDojo if you no longer want them. A connectors service run with `DD_CONNECTORS_CHUNKED_SYNC` unset or `false` closes them on the empty reimport instead. This is a service-wide setting, not a connector option, and hosted customers cannot change it; it is named here so you and DefectDojo Support can tell which behavior applies to your instance.
+* Findings already imported from a project that a project filter later excludes are **not closed automatically**, because its Record is skipped rather than synced. Close or delete them in DefectDojo if you no longer want them.

docs/content/connectors/toolreference/qualys.md

@@ -10,16 +10,21 @@ The Qualys connector imports **VMDR host vulnerability detections** — each joi
 
 A Qualys user account with **VMDR API access**, and your subscription's **API server (platform) URL** — this differs per subscription. Find it in the Qualys UI under **Help \> About**, or on the Qualys [Platform Identification](https://www.qualys.com/platform-identification/) page (for example `https://qualysapi.qualys.com` for US Platform 1, or `https://qualysapi.qg2.apps.qualys.com` for US Platform 2).
 
+The connector only sees the hosts the Qualys user can see, so the user's **scope** (its asset groups or tags) must cover every host you expect to import, and the **VM module** must be enabled on the subscription. A user scoped to a single asset group silently limits the import to that group. The connector is read-only: it calls the Qualys **host list**, **host detection list** and **KnowledgeBase** APIs and nothing else.
+
 #### Connector Mappings
 
 1. Enter your Qualys API server URL in the **Location** field (for example `https://qualysapi.qualys.com`).
 2. Enter the Qualys API username in the **Username** field.
 3. Enter the Qualys API password in the **Secret** field.
 4. Optionally, restrict discovery to part of your subscription with **Host Tags** (see below).
-5. Optionally, enable **Create Endpoints From Hosts** to attach each finding to its host as an endpoint (see below).
-6. Optionally, set a **Minimum Severity** to limit which findings are imported.
+5. Optionally, choose an **Asset Grouping**: one asset per host (the default) or one asset per tag (see below).
+6. Optionally, enable **Create Endpoints From Hosts** to attach each finding to its host as an endpoint (see below).
+7. Optionally, set a **Minimum Severity** to limit which findings are imported.
+
+By default each Qualys host becomes a Record. Detections Qualys has marked **Fixed** are excluded, so reimport closes remediated findings.
 
-Each Qualys host becomes a Record. Detections Qualys has marked **Fixed** are excluded, so reimport closes remediated findings.
+Each host Record carries the host's Qualys details as attributes, including a **TAGS** attribute listing the host's Qualys asset tag names (sorted, comma-separated), which helps when deciding how to map Records to assets. Attributes are captured at discovery: once a Record is mapped, its attributes are not refreshed, so a Record mapped before the TAGS attribute existed does not gain it.
 
 #### Host Tags (optional)
 
@@ -45,9 +50,37 @@ Notes:
 * **Leave it blank to discover every host.** A value that is only spaces or commas is treated as blank.
 * If the tag names match no host, nothing is discovered. Check the spelling against the Qualys UI, and check the visible-host count reported on the connection.
 * The field can be changed after the connection is created.
+* With **Asset Grouping** set to **Tag**, this field is required and also decides which assets are created (see below).
 
 **Testing the connection** ignores this field on purpose, so it still confirms your username and password even when the tag names are wrong.
 
+#### Asset Grouping (optional)
+
+By default the connector creates one Record, and so one asset, per Qualys host. When an application or business unit runs on many hosts, that spreads its findings over many assets, and you have to map each one. The **Asset Grouping** field, under **Import Filters** on the connector form, can group hosts by Qualys tag instead:
+
+| Asset Grouping | Records | Findings on each Record |
+|---|---|---|
+| **Host** (default) | one per Qualys host | that host's detections |
+| **Tag** | one per tag listed in **Host Tags** that at least one host carries | the detections of every in-scope host carrying that tag |
+
+With **Tag**, **Host Tags** is required and does two jobs: it is the scope (which hosts are imported) and the list of tags to group by. For example, with Host Tags set to
+
+```
+Product: Web Portal, Product: Billing API
+```
+
+the connector creates two Records, `Product: Web Portal` and `Product: Billing API`, each holding the findings of every host carrying that tag.
+
+* **Type each tag exactly as it appears in Qualys.** Hosts carrying none of the listed tags are not imported.
+* A host carrying more than one listed tag has its findings imported into **each** of those tag assets, so they count once per asset. Totals added up across tag assets can therefore be higher than the number of distinct detections.
+* A listed tag that no host carries creates no Record.
+* Each Record is named with the tag **as Qualys spells it**. If an asset already exists with exactly that name, auto-mapping routes the tag's findings to it, so you can create or rename assets to match your Qualys tags ahead of time.
+* Every finding carries its **host as an endpoint**, whatever **Create Endpoints From Hosts** is set to. Without it, the same QID on two hosts would look like two identical findings on one asset.
+* Tag Records carry a **TAG_NAME** attribute (the tag) and a **HOST_COUNT** attribute (how many in-scope hosts carried the tag at discovery). Like other attributes, they are not refreshed once the Record is mapped.
+* **Asset Grouping cannot be changed after the connection is created**, because switching would change the identity of every Record. To move from host to tag grouping, create a new connection.
+
+**Removing a tag from Host Tags later:** its Record is no longer discovered and follows the normal lifecycle (flagged `MISSING` if mapped, removed if `NEW`). Until then, Syncs skip it rather than importing an empty result. Findings already imported for that tag are **not closed automatically**; close or delete them in DefectDojo if you no longer want them.
+
 #### Create endpoints from hosts (optional)
 
 By default, findings imported by this connector are linked only to the mapped asset, with no per-host endpoint. On an asset that aggregates several Qualys hosts, that makes it hard to see which systems a finding affects.
@@ -58,6 +91,6 @@ The optional **Create Endpoints From Hosts** toggle attaches each finding's Qual
 * When the detection reports a **port**, it is included, so `web01.example.com:443` and `web01.example.com:8443` remain distinct endpoints.
 * If the asset already has a matching endpoint, the finding is attached to it; otherwise the endpoint is created. No duplicate endpoints are created either way.
 
-The toggle is **off by default**, which keeps the connector's historical behavior: findings stay asset-only. It can be changed after the connection is created, and takes effect on the next Sync — existing open findings gain their endpoints then too, since a Sync reimports them.
+The toggle is **off by default**, which keeps the connector's historical behavior: findings stay asset-only. With **Asset Grouping** set to **Tag**, findings always carry their host as an endpoint and this toggle has no effect. It can be changed after the connection is created, and takes effect on the next Sync — existing open findings gain their endpoints then too, since a Sync reimports them.
 
 **Changing the filter later:** hosts that a newly narrowed filter excludes are no longer discovered. Their existing Records then follow the normal lifecycle for assets the tool stops reporting: **mapped** Records are flagged `MISSING` on the next Sync, and unmapped `NEW` Records are removed. Findings already imported into DefectDojo are not deleted. The filter governs discovery only.