You can find our user documentation at docs.cpanel.net.

Check out our new API beta site!

Child pages
  • WHM API 1 Functions - modsec_add_vendor
Skip to end of metadata
Go to start of metadata

Description

This function adds a new ModSecurity™ vendor rule set to the server.

Important:

In cPanel & WHM version 76 and later, when you disable the Web Server role, the system disables this function.

Examples 



 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/modsec_add_vendor?api.version=1&url=http%3A%2F%2Fwww.example.com%2Fmeta_vendor1.yaml
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/modsec_add_vendor?api.version=1&url=http%3A%2F%2Fwww.example.com.com%2Fmeta_vendor1.yaml
 Command Line
whmapi1 modsec_add_vendor url=http%3A%2F%2Fwww.example.com%2Fmeta_vendor1.yaml


Notes:

  • Unless otherwise noted, you must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command.
  • If you run CloudLinux™, you must use the full path of the whmapi1 command:

    /usr/local/cpanel/bin/whmapi1

 Output (JSON)
{
	"data": {
		"report_url": "https://waf.example.com/api/cpanel_feedback?source=1&rule_set=1.229",
		"vendor_url": "http://www.example.com",
		"inst_dist": "MyVendor-2",
		"vendor_id": "MyVendor",
		"installed": 1,
		"cpanel_provided": 0,
		"name": "My Vendor",
		"dist_sha512": "b55c09bb1835ed4209f0f3ea4a70d099665363f23d3819c0369be429438d675ba2c749dcefdb85cee682ee0bf485558e67d0b0965fe4799865529d943e8e14cb",
		"path": "/usr/local/apache/conf/modsec_vendor_configs/MyVendor",
		"installed_from": "https://example.com/update/meta_MyVendor.yaml",
		"description": "This is an example of a custom vendor set (updated)",
		"archive_url": "http://example.com/update/MyVendor.zip",
		"dist_md5": "307cb5320441ebd712e5581d12100dc9",
		"enabled": 1,
		"supported_versions": [
			"2.7.5",
			"2.7.7",
			"2.8.0",
			"2.9.0",
			"2.9.1",
			"2.9.2",
			"2.9.3"
		]
	},
	"metadata": {
		"version": 1,
		"reason": "OK",
		"result": 1,
		"command": "modsec_add_vendor"
	}
}
 Output (XML)
<result>
   <data>
	 <report_url>https://waf.example.com/api/cpanel_feedback?source=1&rule_set=1.229"</report_url>
      <archive_url>http://example.com/update/MyVendor.zip</archive_url>
      <cpanel_provided>0</cpanel_provided>
      <description>This is an example of a custom vendor set (updated)</description>
      <dist_md5>307cb5320441ebd712e5581d12100dc9</dist_md5>
      <enabled>1</enabled>
	<dist_sha512>b55c09bb1835ed4209f0f3ea4a70d099665363f23d3819c0369be429438d675ba2c749dcefdb85cee682ee0bf485558e67d0b0965fe4799865529d943e8e14cb"</dist_sha512>
      <inst_dist>MyVendor-2</inst_dist>
      <installed>1</installed>
      <installed_from>https://example.com/update/meta_MyVendor.yaml</installed_from>
      <name>My Vendor</name>
      <path>/usr/local/apache/conf/modsec_vendor_configs/MyVendor</path>
      <vendor_id>MyVendor</vendor_id>
      <vendor_url>http://www.example.com</vendor_url>
	  <supported_versions>
			<supported_versions>2.7.5</supported_versions>
			<supported_versions>2.7.7</supported_versions>
 			<supported_versions>2.8.0</supported_versions>
 			<supported_versions>2.9.0</supported_versions>
 			<supported_versions>2.9.1</supported_versions>
 			<supported_versions>2.9.2</supported_versions>
			<supported_versions>2.9.3</supported_versions>
	  </supported_versions>
   </data>
   <metadata>
      <command>modsec_add_vendor</command>
      <reason>OK</reason>
      <result>1</result>
      <version>1</version>
   </metadata>
</result>


Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
url

string

Required

The YAML metadata that describes the vendor and how to obtain its rules.

A valid URL.
 Click to view...

https://example.com/update/meta_MyVendor.yaml

enabled

Boolean

Whether to enable the vendor.

This parameter's value defaults to 1.

  • 1 — Enabled.
  • 0 — Disabled.
1

Returns

ReturnTypeDescriptionPossible valuesExample 
archive_urlstring

The URL to the vendor's rule set archive.

Note:

The system will download a set of rules that is compatible with your version of ModSecurity.

A valid URL.
 Click to view...

http://example.com/update/MyVendor.zip

installedBooleanWhether the function installed the vendor.
  • 1 — Installed.
  • 0Not installed.
1
enabledBooleanWhether the function enabled the vendor.
  • 1 — Enabled.
  • 0Not enabled.
1
cpanel_providedBooleanWhether cPanel, L.L.C. provided the vendor.
  • 1 — cPanel-provided.
  • 0Not cPanel-provided.
0
vendor_urlstringThe vendor's website URL.A valid URL.

http://www.example.com

vendor_idstringThe vendor's unique short name.A valid string.

MyVendor

namestringThe vendor's name.A valid string.My Vendor
descriptionstringThe vendor's description.A valid string.
 Click to view...

This is an example of a custom vendor set (updated)  

inst_dist

string

The rule set's unique identifier.

A valid string.

MyVendor-2

dist_md5

stringThe download's MD5 checksum value.A valid string.
 Click to view...

307cb5320441ebd712e5581d12100dc9

installed_from

stringThe vendor's metadata file URL.A valid URL.
 Click to view...

https://example.com/update/meta_MyVendor.yaml

path

stringThe absolute path to the directory that contains the vendor's configuration files.A valid absolute directory path.
 Click to view...

/usr/local/apache/conf/modsec_vendor_configs/MyVendor 

report_urlstringThe URL to which the system will send reports.A valid URL.
 Click to view...

https://waf.example.com/api/cpanel_feedback?source=1&rule_set=1.229

dist_sha512stringThe download's sha512 hash.A valid string.
 Click to view...

b55c09bb1835ed4209f0f3ea4a70d099665363f23d3819c0369be429438d675ba2c749dcefdb85cee682ee0bf485558e67d0b0965fe4799865529d943e8e14cb

supported_versionsarrayA list of the ModSecurity versions that the vendor supports.A list of version numbers.2.7.5