/api/2.0/fo/auth/mongodb/
[POST]
Create, update, list and delete MongoDB records for authenticated scans of MongoDB instances running on Unix. Vulnerability and compliance scans are supported (using VM, PC).
- Technologies supported: MongoDB 3.x
- Unix authentication is required for compliance scans using the PC app. Make sure the IP addresses you define in your MongoDB records are also defined in Unix records.
- We strongly recommend you create one or more dedicated user accounts to be used solely by the Qualys Cloud Platform to authenticate to MongoDB instances.
Requirement - You must configure authentication credentials on target hosts.
System created authentication records supported - You can allow the system to create MongoDB authentication records for auto discovered instances and scan them. This is supported for Unix installations only. To enable this feature, you must first create MongoDB System Record Templates using the is_template input parameter and specifying login credentials.
How it works - During scanning we'll authenticate to one or more instances on a single host using all MongoDB records in your account. For compliance scans, you can scan multiple MongoDB instances on a single host and port combination.
Download Qualys User Guide - MongoDB Authentication (.pdf)
Parameter |
Description |
action={action} |
(Required) Specify create, update, delete (using POST) or list (using GET or POST). See List Auth Records for type |
echo_request={0|1} |
(Optional) Specify 1 to view (echo) input parameters in the XML output. By default these are not included. |
title={value} |
(Required to create record) A title for the record. The title must be unique. Maximum 255 characters (ascii). |
comments={value} |
(Optional to create or update record) User defined comments. Maximum of 1999 characters. |
is_template={0|1} |
(Optional for create request, not valid for update request). By default, a new record is a regular MongoDB record. Specify 1 to create a MongoDB system record template. You must also specify login credentials, which are described below. See System created MongoDB authentication records |
status={0|1} |
(Optional) The record status, active or inactive. By default, a new record is set to active (1). Set to 0 for inactive record or 1 for active record. (This parameter applies to system created and user created MongoDB records. It cannot be specified for MongoDB system record templates.) |
save_as_user_auth={0|1} |
(Optional for update request, not valid for create request) Specify 1 to update a system created record and save it as a user created record. If another MongoDB record already exists with the same IP address and target configuration then an error will be returned. (This parameter applies only to system created MongoDB records. It cannot be specified for user created MongoDB records and it cannot be specified for MongoDB system record templates.) |
database_name={value} |
(Required for create request) The username of the account to be used for authentication to the database. If password is specified this is the username of a MongoDB account. If login_type=vault is specified, this is the username of a vault account. Maximum 255 characters (ascii). |
port={value} |
(Required for create request) The port where the database instance is running. Default is 27017. |
ssl_verify={0|1} |
(Required if ssl_verify=1) A list of FQDNs for all host IP addresses on which a custom SSL certificate signed by a trusted root CA is installed. |
hosts={value} |
(Required if ssl_verify=1) A list of FQDNs for all host IP addresses on which a custom SSL certificate signed by a trusted root CA is installed. |
Target Hosts |
|
ips={value} |
(Required to create record, optional to update record) Add IP addresses of the hosts you want to scan using this record. Overwrites (replaces) the IP address(es) in the IP list for an existing authentication record. The IPs you specify are added, and any existing IPs are removed. You may enter a combination of IPs and IP ranges. |
add_ips={value} |
(Optional to update record) Add IP address(es) to the IP list for an existing authentication record. You may enter a combination of IPs and IP ranges. |
remove_ips={value} |
(Optional to update record) IPs to be removed from your record. You may enter a combination of IPs and ranges. Multiple entries are comma separated. |
network_id={value} |
(Optional to create or update record, and valid when the networks feature is enabled) The network ID for the record. |
Login credentials |
|
credential_type=local|external |
(Optional) The credential type is local by default which means login credential type is local authentication. You need to set credential type to external for LDAP authentication option. |
cleartext=0|1 |
(Optional) You must set credential_type to external to use cleartext parameter. The default value for cleartext is 0. You must set this parameter to 1 for successful MongoDB authentication for LDAP. |
login_type={basic|vault|pkcert} |
(Optional) The login type is basic by default. You can choose vault (for vault based authentication) or pkcert (for certificate based authentication). |
username={value} |
(Required to create record when login_type=basic or login_type=vault) The username of the MongoDB account to be used for authentication. Maximum 100 characters (ascii). |
password={value} |
(Required to create record when login_type=basic) The password of the MongoDB account to be used for authentication. Maximum 100 characters (ascii). |
Vault |
|
vault_type={value} |
(Required to create record when login_type=vault) The vault type to be used for authentication. |
vault_id={value} |
(Required to create record when login_type=vault and you want to retrieve private key from vault) The vault ID where you want to retrieve the private key from. Certain vaults support this capability. |
{vault parameters} |
(Required to create record when login_type=vault) Vault specific parameters required depend on the vault type you’ve selected. See Vault Parameters |
private_key_vault_id={value} |
(Required to create record when login_type=vault and you want to retrieve passphrase from vault) The vault ID where you want to retrieve the passphrase from. Certain vaults support this capability. |
passphrase_vault_id={value} |
(Required to create record when login_type=vault and you want to retrieve passphrase from vault) The vault ID where you want to retrieve the passphrase from. Certain vaults support this capability. |
private_key={value} |
(Required to create record when login_type=pkcert) The private key to be used for authentication. Certain vaults support this capability. |
passphrase={value} |
(Required to create record when login_type=pkcert and passphrase_vault_id is not specified) The private key passphrase value of an encrypted private key. Maximum 255 characters (ascii). Certain vaults support this capability. |
certificate={value} |
(Optional to create or update record when login_type=pkcert ) The passphrase X.509 certificate content. |
require_cert={0|1} |
(Optional) Specify 1 to login with certificates/private keys along with login type Basic | vault. By default value will be 0 |
When we auto discover MongoDB instances, we’ll discover the target configuration for each instance but not the login credentials. We’ve introduced a new configuration called “MongoDB authentication record template” that you’ll use to provide MongoDB login credentials for system created records. You’ll create the system record template and then select it in the option profile used for discovery scans. The template is linked automatically to the system created records created as a result of the scan.
- We’ll auto discover MongoDB instances on each scanned host and create authentication records for those instances. We support auto discovery and system record creation for MongoDB instances running on Unix platforms. Make sure you have Unix authentication records in your account for hosts running MongoDB.
- When we create MongoDB authentication records for discovered instances, we’ll insert the credentials from the MongoDB system record template you selected in the option profile.
- You can easily rotate MongoDB passwords. Simply edit the credentials in the MongoDB system record template and all MongoDB records linked to the template will be updated to use the new credentials with no additional scan or action by you.
- You can edit individual MongoDB system created records and save them as user created. This allows you to change the credentials for individual records without changing the credentials for all records associated with a template.
Here’s the basic flow for MongoDB instance discovery and auto record creation. Note - We support auto discovery and system record creation for MongoDB instances running on Unix platforms. Make sure you have Unix authentication records in your account for hosts running MongoDB.
1) Create an MongoDB system record template and enter the login credentials you want to use for system created records.
2) Select the MongoDB system record template in the compliance option profile you want to use for discovery scans.
3) Launch your discovery scan. Your scan results will list the auto discovered instances.
4) List your MongoDB authentication records. For each system created record, you’ll see the template associated with the record.
API request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: curl sample" -d "action=create&title=API-mongodb-basic-login&username=root&password=12345abc&ips=10.20.32.239&comments=mongo-basic-login&unix_conf_path=/etc/mongod3.conf&port=28020&ssl_verify=0&database_name=admin" "https://qualysapi.qualys.com/api/2.0/fo/auth/mongodb/"> file.xml
XML output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE BATCH_RETURN SYSTEM "https://qualysapi.qualys.com/api/2.0/batch_return.dtd">
<BATCH_RETURN>
<RESPONSE>
<DATETIME>2018-04-12T22:43:27Z</DATETIME>
<BATCH_LIST>
<BATCH>
<TEXT>Successfully Created</TEXT>
<ID_SET>
<ID>125709</ID>
</ID_SET>
</BATCH>
</BATCH_LIST>
</RESPONSE>
</BATCH_RETURN>
API request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl Sample" -d "action=create&title=API-mongo-vault-CA_Access&ips=10.20.32.239&comments=mongo-CA-Access-vault_login&unix_conf_path=/opt/mongodb4.conf/&port=27010&login_type=vault&vault_type=CA AccessControl&vault_id=166657&end_point_name=name&end_point_type=type&end_point_container=container&username=joe_user" "https://qualysapi.qualys.com/api/2.0/fo/auth/mongodb/" > file.xml
XML output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE BATCH_RETURN SYSTEM "https://qualysapi.qualys.com/api/2.0/batch_return.dtd">
<BATCH_RETURN>
<RESPONSE>
<DATETIME>2018-03-12T20:11:47Z</DATETIME>
<BATCH_LIST>
<BATCH>
<TEXT>Successfully Created</TEXT>
<ID_SET>
<ID>125711</ID>
</ID_SET>
</BATCH>
</BATCH_LIST>
</RESPONSE>
</BATCH_RETURN>
API request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d "action=create&title=Sample1&username=mlqa&password=12345abc&ips=10.20.32.107&comments=Creating through API v2.0&unix_conf_path=/etc/mongod3111.conf&port=28021&ssl_verify=0&database_name=admin&credential_type=external&cleartext=1" "https://qualysapi.qualys.com/api/2.0/fo/auth/mongodb"
XML output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE BATCH_RETURN SYSTEM "https://qualysapi.qualys.com/api/2.0/batch_return.dtd">
<BATCH_RETURN>
<RESPONSE>
<DATETIME>2020-09-08T06:15:39Z</DATETIME>
<BATCH_LIST>
<BATCH>
<TEXT>Successfully Created</TEXT>
<ID_SET>
<ID>3052106</ID>
</ID_SET>
</BATCH>
</BATCH_LIST>
</RESPONSE>
</BATCH_RETURN>
API request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: curl sample" -d
"action=create&title=mongo_auth_basic_cert&username=joe_user&passw
ord=abc123&login_type=basic&ips=10.20.30.40&database_name=admin&po
rt=27019&require_cert=1&unix_conf_path=/etc/mongod2.conf&ssl_verif
y=1&hosts=mlcent76mdb34.s2012r2.qualys.com'
--header 'X-Requested-With: qweb' \
--header 'Authorization: Basic YXdzX2FrOlF3ZWJANDYzMA==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'certificate=-----BEGIN CERTIFICATE-----
MIIErDCCApSgAwIBAgIBIDANBgkqhkiG9w0BAQUFADCBljEbMBkGA1UEAwwSU2Nh
bm5lciBRQSBSb290IENBMRMwEQYDVQQIDApDYWxpZm9ybmlhMQswCQYDVQQGEwJV
UzEeMBwGCSqGSIb3DQEJARYPbWxxYUBxdWFseXMuY29tMRswGQYDVQQKDBJRdWFs
eXMgRW5naW5lZXJpbmcxGDAWBgNVBAsMD1NjYW5uZXIgUUEgVGVhbTAeFw0yMTA2
MTQyMTEwMDBaFw0yNDA2MTMyMTEwMDBaMIGMMR4wHAYDVQQDDBVtbGNlbnQ3Nm1k
YjM0X2NsaWVudDExEzARBgNVBAgMCkNhbGlmb3JuaWExCzAJBgNVBAYTAlVTMR4w
HAYJKoZIhvcNAQkBFg9tbHFhQHF1YWx5cy5jb20xFDASBgNVBAoMC1F1YWx5cyBJ
bmMuMRIwEAYDVQQLDAlNTFFBIFRlYW0wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAw
ggEKAoIBAQCxPNX+jExoBJqbftSbOeMYdWgCP8o8YR+aqjS6ZqroX9i8dfFCsVc3
5ePxBDOUr5p/DivhvMWsBZsZp2qpSOAjj2vKQV4M7VNvR7h9mjQRpruLOPrCFFup
WWy+zSCzRskiYWhRGd8V5XWvaJhNytneBLsUX6l+1SAwFC+eD/M2oA4VhipAK612
sKTn7yUjYBTODjox+dumKpFTdoPfjaCO923K2fcMNrLUVYQNbibxygsQK6qFJnVl
XJ1LCSVyTBJLuOWrgBATrvcMh9Wv5U0XFRp1u6t2pqnUqkzRsa5jtGR3GBfR3lUu
1JUyo4Kx1QrDw2I3vkYFA/dVv2dTEUgBAgMBAAGjDTALMAkGA1UdEwQCMAAwDQYJ
KoZIhvcNAQEFBQADggIBAL5MYQ8XinuSInZYQgywYFWlhZJJOSEqD4B4DqDfset4
v/7OjDCDWYH8DeObWcHuJgHh1vADpHIYDjfJCPnAPBKgIquVz9QaLUgtV+u1fJDe
Hpxr6IACaizlV0IId6JmoSR+MR2LPig0mi7Du4r07vqUWBB8za4ZxDVtQNkcPI/k
8/Sgj+kyr8hF4up8kniTMEaD/7eZ7MNmYR1BFygcZ/ieYRfdWVMlOvYDxVT20tCK
V7OzI12wXy/J37xdm8BaIkkoJyKPBwP396c4BlIrC5bDvBGRH89VhNscWryhPz9l
CrNvhegnqC0sxi7b4KOEMH3NtbETRZT8IhLkzHZTF+SqxUNkqjD1jdnM3cq0Ab3d
TdB5Ul7B3IjwgtnNES6pxHaX//ycRvGo9v2rzJO8TCtsd0o21uaLXwJmqJ5qhFPz
iX92jYZqEWm3wSD2XMI8kolr4txNfzH9zwAcEGdtBqUlTJcrdOU8IUn3pqISqZkr
wWpiBeS5eU/YbnkhSz2l6bX1x0qaQWv8h16YusvBMjfb2jBWHkED/osRFA7F5f11
XBNipcTrie1iIDY758iDbFrwWaza/9cg0awluyOa560rkyhZTWxwoZkvUz/rnVE7
2UaXkwPxhWAHx3jzfcQca8GTIEVbzuDkg+jcwCoaRNI3IG3339PQE/eF50yiE1YM
-----END CERTIFICATE-----' \
--data-urlencode 'private_key=-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAsTzV/oxMaASam37UmznjGHVoAj/KPGEfmqo0umaq6F/YvHXx
QrFXN+Xj8QQzlK+afw4r4bzFrAWbGadqqUjgI49rykFeDO1Tb0e4fZo0Eaa7izj6
whRbqVlsvs0gs0bJImFoURnfFeV1r2iYTcrZ3gS7FF+pftUgMBQvng/zNqAOFYYq
QCutdrCk5+8lI2AUzg46MfnbpiqRU3aD342gjvdtytn3DDay1FWEDW4m8coLECuq
hSZ1ZVydSwklckwSS7jlq4AQE673DIfVr+VNFxUadburdqap1KpM0bGuY7RkdxgX
0d5VLtSVMqOCsdUKw8NiN75GBQP3Vb9nUxFIAQIDAQABAoIBAQCKiPzTnKJUY9Td
WgOg2Vxyz8Jej7HqBBiJ8iSI1pscS17D4ISWFrwPyzeiOiB/RctDKLaQGdeAoFkd
ckjizT21TfN5AiMbg53Fy4+fTZsJeQP6zKzkarlC480mTnwS5W9t2imJyuke2l5k
nyL9G2O0MIpyYFvB8aDZM84MhHcc6CuRme3+VS9kFaIC7wNoEzUrGZt8CE1QDZh9
zKQsVLT5y7Hk+yiDLZ7BkgecFJ52J4xcYzIQhfrfIQp0UmCcKPslHrX3Xzens1GO
AyCkRIRfaI+NIwygrzVtwPTdKNOz+E4K5bmwwNUCdBjZi4DGPxZvobktD6FI7pjA
pHcWZL2BAoGBAOxAvhc5H/66MexOdBhtNRkueMHVWgeAnHYlcGvTjumRqbhipJIc
oVQHFcnFEXrP762dSo7QA2yg0SrhBD+U0iCkDKnzNQnDsXYftDSMNrhhEIznMUvX
JWn17yrXtROsq4oFpvSdJ33fZQHEy8K6aCOGRbAsWjAjAfb98acQHxe5AoGBAMAN
TisS8ZZShhEfKussVbcJYuIHqyVvA2TV3OetMt8tMiToNVOsRukV6Hnf9DFXOdBh
ddxFbGFJiaFDduzjjig8m53FCmmOtqnOxL5lxckx2ajxxGKfdKpSOG0OzDbxEKjF
uGX9VviOlpbt2JPuHF7qc850xf54z9QRu7OX+UaJAoGARKxFFScLv9WLsW7UnE0S
RDGX9G/57XhbApS7avxh7E7lEK3LvJUJ6AzvLmlUPWi3+LVh+MVKWYcdheNGgtzV
f5tv+u6xGheCPB3XGfcv6MR+NRb24160h2pvjPqKrh9g9YvTDgOoeRQ4nh0ARag9
oSXkl+MsjBWA+rSyS6eKAjECgYEAiRR2KPSaj8tTekEe50F75OvEMsV6eXulloG3
7X2IhBfEZOeBuLmM264Rg3xA1j8GOyB1ecXrt/0/SWXYKvm5bCrmgFQ2PGXrJ4U4
lRYbeKImVBpNLH/YTAHn2J/pT4X9eBm4psOPIlbUUeJu5hfdFDqQclqTQDGHVj1a
FrRw7tECgYBEuc85ghJunoV7hENuolP19+ppaiyH98q4Mc6vpkoEItuoKjWfH1Yr
98QtS58boBphSCNU4qL51dqnEAzCd0udYINxLawaosI3aaUOEGIUUa7IO7e7qUl8
Y4pb3owl0zwdpnyEgdSpuCW8N1Gnsiiur2fJ1NeAaHCF4cG3Se7bfw==
-----END RSA PRIVATE KEY-----'”
\"https://qualysapi.qualys.com/api/2.0/fo/auth/mongodb/" >
file.xml
XML output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE BATCH_RETURN SYSTEM
"https://qualysapi.qualys.com/api/2.0/batch_return.dtd">
<BATCH_RETURN>
<RESPONSE>
<DATETIME>2022-06-23T11:15:21Z</DATETIME>
<BATCH_LIST>
<BATCH>
<TEXT>Successfully Created</TEXT>
<ID_SET>
<ID>6298437</ID>
</ID_SET>
</BATCH>
</BATCH_LIST>
</RESPONSE>
</BATCH_RETURN
<platform API server>/api/2.0/batch_return.dtd
<platform API server>/api/2.0/fo/auth/mongodb/auth_mongodb_list_output.dtd