Frequently Asked Questions

1. Add the desired field name under custom field section and map it with the respective field name from the API response. For example, to add the field qg host id, the custom field section should have
   
   "QG Host ID": {

           "value":"${QG_HOSTID}",

           "customFieldId": ""

    }

   In the above example - "QG Host ID" is the name of the field in your Jira instance and ${QG_HOSTID} is the field name from the API response.

2. Once the file is updated with the new fields, ensure there are no JSON syntax errors in it to avoid any Jira connector application errors.
3. In cases where you update the ticketing template after running the Jira Connector application, if you have configured as both admin or non-admin user, then create the respective field in your Jira instance manually. Keep the respective field type. We support label & Select List (Single & multi choice), Number, Component System field, Paragraph, Read Only, Short text (plain text only). Restart the Jira client service for the ticketing template updates to take effect.
4. For field names, you can refer to the API outputs of the following using curl or postman Host Detection API        https://qualysapi.qg1.apps.qualys.in/api/2.0/fo/asset/host/vm/detection
   WAS API -https://qualysapi.qualys.eu/qps/rest/3.0/search/was/finding

The Jira Connector supports setting mandatory fields on the respective Ticketing Schemes. You may refer to Mandatory Fields in Ticketing Schemes to learn more.

Using docker compose is recommended as

• The Jira connector application requires multiple containers to run at the same time
• There is a startup dependency between the two containers that spin for this application

However, if you still lean towards, docker run, you can execute the following commands to
achieve the same,

1. Create a bridged network using the command docker network create -d bridge qualys-jira-connector
2. Create named volume using command docker volume create qualys-jira-volume
3. Spin Qualys client service container using command

   docker run -d\

   --network=qualys-jira-connector \

   --volume qualys-jira-volume:/opt/qualys/common/jiraconnector/ \

   --env SPRING_REDIS_HOST=#VM-ip-Address \

   --env SPRING_REDIS_PORT=#Port-number \

   --env SPRING_REDIS_USER=default \

   --env SPRING_REDIS_PASSWORD=JiraConnectorRedisDB \

   qualys/qualys-client-for-jira-integration:1.1.0

4. Spin Qualys Redis client service container using command 

   docker run -d\\

   --network=qualys-jira-connector \

   --publish port-no-same-as-SPRING_REDIS_PORT:port-no \

   --volume qualys-jira-volume:/opt/qualys/common/jiraconnector/ \

   qualys/redis-test:1.1.0

5. Spin Qualys Jira client service container using command

   docker run -d\\

   --network=qualys-jira-connector \

   --volume qualys-jira-volume:/opt/qualys/common/jiraconnector/ \

   qualys/jira-client-for-jira-integration:1.1.0

After step 5, your application should be up and running.

Cause: File is renamed correctly but at this point config.json file does not contain valid input yet hence error is logged.

Solution: Refer to Configurations.

They connect through the network defined in docker-compose file. Refer to Understand Application Services and Component

Docker compose has command line option of '-p' using which you can specify the project name.

Example,
docker-compose -p jira-connector-1 up.

To run multiple instance using the same compose file, all you have to do is change the
value of the '-p' parameter. But, be careful of,

• Not abusing the api limit for both Qualys and Jira APIs.
• Additional consumption of resources such as memory, disk space, etc. For each new instance of application, separate volumes and network are created.

Hence, it is only advised to run multiple instances when keeping the above points in mind.

Not at all! Any data that the application writes to the volume placed on your host gets preserved in its volume directory until you explicitly delete the volume.

Yes, you can. Restart your Jira Client service container to ensure template changes are effective.

Every instance of re-updating the config.json file triggers both of the services from scratch. Qualys Client service re-initiates the schedule and fetch for Host detection/ KnowledgeBase data. Whereas, Jira Client service tries to create custom issue types and fields in the instance, unless they are already present in the instance.

The jiraconnectorconfig directory contains the files, jira_connector_default_config.json - The Jira connector uses a flag (true/false) in this file as the communication bridge between Qualys Client service container and Jira Client service container to provide status of the encryption.

jiraSettings.json - This file contains details related to Project profile, Issue Types and custom fields.

password_conf.json - This file contains encrypted passwords

You should not make any changes to these files.

For ticketing scheme 1, each Host Vulnerability ticket is processed/updated for each related Vulnerability ticket. Every time a Host Vulnerability ticket is updated, the count of processed ticket is increased.

So, the final 'Total tickets processed count' is higher than actual created/updated tickets.

No, you can not. Removal of any keys leads to errors when running the app.

We recommend not removing any input field from the json file. If a field has no value,leave it empty like this -"filter" : ""

Valid config.json sample with authenticated proxy and API filters

      
 {
   "credentials":{
      "qualys":{
         "apiUrl":"https://qualysapi.qg2.apps.qualys.com",
         "username":"qualys-user",
         "password":"qualys-password"
      },
      "jira":{
         "instanceUrl":"https://jira-instance.atlassian.net/",
         "username":"admin@jira.com",
         "apiToken":"jira-api-token",
         "instanceType":"onCloud"
      },
      "proxy":{
         "host":"10.10.10.10",
         "port":"3128",
         "username":"proxy-user",
         "password":"proxy-password"
      }
   },
   "profile":[
      {
         "profileId":"HD",
         "name":"Host Detection",
         "active":true,
         "frequencyInMinutes":30,
         "filter":"show_asset_id=1&show_tags=1",
         "hostAssetApiFilter":"show_trurisk=1",
         "projectKey":"TS1",
         "ticketingScheme":1
      },
      {
         "profileId":"KB",
         "name":"Knowledgebase",
         "active":true,
         "frequencyInMinutes":30,
         "filter":"",
         "projectKey":"TS1",
         "ticketingScheme":1,
         "batchSize":"500"
      },
      {
         "name":"Web App Scan",
         "profileId":"WAS",
         "active":true,
         "frequencyInMinutes":30,
         "filter":"{\"ServiceRequest\":{\"preferences\":{\"verbose\":\"true\",\"limi
tResults\":
\"50\"},\"filters\":{\"Criteria\":[{\"field\":\"type\",\"operator\\
":"\\""IN\",\"value\":\"VULNERABILITY,INFORMATION_GATHERED,SENSITIVE_
CONTENT\"},{\"field\":\"findingType\",\"operator\":\"EQUALS\",\"va
lue\":\"QUALYS\"}]}}}",
         "projectKey":"TS3",
         "ticketingScheme":"3"
      }
   ]
}   

Valid config.json sample with un-authenticated proxy and No API filters

{
   "credentials":{
      "qualys":{
         "apiUrl":"https://qualysapi.qg2.apps.qualys.com",
         "username":"qualys-user",
         "password":"qualys-password"
      },
      "jira":{
         "instanceUrl":"https://jira-instance.atlassian.net/",
         "username":"admin@jira.com",
         "apiToken":"jira-api-token",
         "instanceType":"onCloud"
      },
      "proxy":{
         "host":"10.10.10.10",
         "port":"3128",
         "username":"",
         "password":""
      }
   },
   "profile":[
      {
         "profileId":"HD",
         "name":"Host Detection",
         "active":true,
         "frequencyInMinutes":30,
         "filter":"",
         "hostAssetApiFilter":"",
         "projectKey":"TS1",
         "ticketingScheme":1
      },
      {
         "profileId":"KB",
         "name":"Knowledgebase",
         "active":true,
         "frequencyInMinutes":30,
         "filter":"",
         "projectKey":"TS1",
         "ticketingScheme":1,
         "batchSize":"500"
      },
      {
         "name":"Web App Scan",
         "profileId":"WAS",
         "active":true,
         "frequencyInMinutes":30,
         "filter":"",
         "projectKey":"TS3",
         "ticketingScheme":"3"
      }
   ]
}      
    

You can contact Qualys support to report any issue related to the Jira connector.

While reporting an issue, make sure you provide the following details:

• A detailed summary of the issue
• The docker-compose.yml file you are using
• Following evidences from docker volume (qualys-jira-volume/_data)
  • Complete logs for Qualys client and Jira client services.
  • config file (post removing passwords in it)
  • db
  • ticketing template files used
  • output files, if any (even if in errored state)
• In case of a startup error, provide complete error triggered during startup, along
  with:
  • Base OS of the host where you are setting up the Jira Connector application
  • Docker Version
  • Docker compose installation type and version
  • Socket on which docker runs (Eg. UNIX, TCP)
• Output of the following commands:
  • docker inspect volume <jira-connector-volume-name>
  • docker inspect network <jira-connector-network-name>
  • docker inspect <qualys-client-service-container>
  • docker inspect <jira-client-service-container>

1. The Qualys client service populates batchSize into HD and WAS profile, and hostAssetApiFilter in KB and WAS profile. This is done to maintain consistency across the profiles.
2. Profiles where these fields are not relevant are populated with null' value.
3. Qualys Client service does not process irrelevant fields populated in profiles. You can ignore those fields.

1. Follow the steps below to find your ticket templates.
2. Run the docker volume ls command. The output shows all the docker volumes in use on your system.
3. Find the volume whose name is in ‘<name of directory>_qualys-jira-volume’ format, where <name of directory> is the directory where your connnector’s docker-compose.yml file is located. Copy the volume name.
4. Run the docker volume inspect <your volume name> command. Replace <your volume name> with the actual name you copied in step 2. The output shows JSON with all the details of the volume.
5. From the output shown in step 3, copy the value of Mountpoint key. This is the path to the root of connector’s directory. Copy the directory path – you will use it to navigate to templates.
6. Finally, go to <path copied in step 4>/templates directory to see all the templates used by the connector.

1. You can edit the corresponding ticket template and use the ${RESULTS} token as shown in the example below.
   
   "description": "Vulnerability details: ${VULN.TITLE}, Result:${RESULTS}"
   
   Ensure that you back up the current copy of the template, so that you can revert to that in case required.
2. Our recommendation is to add the results in the Description field, since results are multi-line data.
3. Save the updated template upon change.
4. On the next connector run, where this updated template gets referred, the connector will parse the result section from the Host List Detection API output and include it in the ticketing payload. The result section can be seen in the ticket as shown in the example below.
   
   Vulnerability details: OpenSSH Sensitive Information Disclosure Vulnerability, 
   Result: Vulnerable OpenSSH version for sshd(8) detected on port 22 over TCP - SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.7

If a user is utilizing the same instance for multiple modules and has established distinct projects corresponding to each module, there is no requirement to duplicate common generic custom fields across different projects. Instead, extend the context of the already created custom field by associating the projects with that field and supporting the required issue type. This approach minimizes the effort of creating common fields repeatedly and addresses potential errors in the Jira client logs related to the creation of tickets for those common fields.