Document the URL_DOWNLOAD threat intelligence source type

[kolchfa-aws]

Description

Addresses user feedback submitted through the documentation feedback widget on July 29, 2026:

URL_DOWNLOAD, possible formats, and the source "url_download" are all undocumented

The Source API page documented only the S3_CUSTOM and IOC_UPLOAD source types. The strings URL_DOWNLOAD and url_download appeared nowhere in the threat intelligence documentation.

Importantly, URL_DOWNLOAD is not a third source type users can create — it is reserved for built-in feeds, and a create request returns a 400. This PR documents the type and its restrictions rather than adding a create example that would fail for every reader.

Changes:

• Added URL_DOWNLOAD to the type parameter description and documented the source_config.source.url_download.* parameters.
• Added a "URL_DOWNLOAD type sources" section covering how to list built-in feeds, the supported feed format, how to activate or deactivate a feed, and the delete restriction.
• Corrected an existing error in the Refresh section, which claimed it "Only supports the S3_CUSTOM type source." Refresh actually excludes only IOC_UPLOAD.

Testing

Parameter names came from UrlDownloadSource.java field constants and were confirmed against live API responses on a local 3.8.0 cluster. Verified empirically:

• Creating a URL_DOWNLOAD source returns URL_DOWNLOAD source type cannot be created via the REST API. It is reserved for internal use only.
• One built-in source ships by default: alienvault_reputation_ip_database.
• Update permits only toggling enabled_for_scan; other field changes are rejected, and schedule is required.
• Delete returns Cannot delete built-in tif source config.
• Refresh succeeds on the URL_DOWNLOAD feed and fails on IOC_UPLOAD, confirming the Refresh correction.
• csv is the only supported feed_format.

Two spellings look like typos but are genuine upstream field names, preserved verbatim so copy-paste works: has_csv_header_field and csv_ioc_value_colum_num.

Note for reviewers

The page is written against current behavior without version qualifiers. The REST-API restriction is present in main, 3.7, and 3.8 but absent from 2.19, 3.0, 3.5, and 3.6, and the backport PRs (opensearch-project/security-analytics#1671–#1680) are still open. If version callouts are wanted, that depends on whether those backports land.

The version that introduced the type is not claimed on the page because it could not be confirmed. Separately, CUSTOM_SCHEMA_IOC_UPLOAD also exists in Source.java and remains undocumented — out of scope here.

Issues Resolved

N/A — reported through the site feedback widget.

Check List

• Commit changes are signed off (git commit -s)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[github-actions]

Thank you for submitting your PR. The PR states are In progress (or Draft) -> Tech review -> Doc review -> Merged.

Before you submit your PR for doc review, make sure the content is technically accurate. If you need help finding a tech reviewer, tag a maintainer.

When you're ready for doc review, tag the assignee of this PR. The doc reviewer may push edits to the PR directly or leave comments and editorial suggestions for you to address (let us know in a comment if you have a preference).

[kolchfa-aws]

@AWSHurneyt could you review this PR?

[AWSHurneyt]

Tagging @kanwaljeetd to assign reviewer from the security analytics plugin team.

[eirsep]

let's not mention that URL_DOWNLOAD is a valid value.

[eirsep]

above mentioned sentence calling out url_download is internal only suffices.

[kolchfa-aws]

@eirsep Thanks - removed the url_download from valid values.