The VINCE API is still under development, but we are making this documentation available for folks who might want to try it out in the meantime. Please let us know what changes you'd like by submitting a work in progress. Please provide feedback through VINCE or GitHub.
Table of Contents
...
Authentication
...
First, you have to login to the VINCE COMM UI and generate a key in your profile:
Edits in progress. This note will be removed when the page is stable. - Allen D. Householder
Code Block
language
py
# get information about organizations you belong to:
api = 'https://kb.cert.org/vince/comm/api/vendor/'
headers={'Authorization': "Token {}".format(token) }
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
language
py
# get a list of your cases
headers={'Authorization': "Token {}".format(token)}
api = 'https://kb.cert.org/vince/comm/api/cases/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
# get information about VU#701852
api = 'https://kb.cert.org/vince/comm/api/case/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
# get all posts for case VU#701852
api = 'https://kb.cert.org/vince/comm/api/case/posts/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
# get the original report for VU#701852
api = 'https://kb.cert.org/vince/comm/api/case/report/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
# get the vuls for VU#701852
api = 'https://kb.cert.org/vince/comm/api/case/vuls/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
# get all the vendors involved in VU#701582 (also gets their status and statements)
api = 'https://kb.cert.org/vince/comm/api/case/vendors/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
# get a list of your cases
headers={'Authorization': "Token {}".format(token)}
api =
Code Block
# get all the vendors and their status/statement/references for each specific vul
api = f'https://kb.cert.org/vince/comm/api/case/vendors/vuls/{case}/'
headers={'content-type':'application/json', 'Authorization': "Token {}".format(token) }
r = requests.get(api, headers=headers, cases/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
language
js
API: /vince/comm/api/cases # get thea listvulnerabilityofnote,casesifinvolvedavailableinapi[ = f'https://kb.cert.org/vince/comm/api/case/note/{case}/'
headers={'content-type':'application/json', 'Authorization': "Token {}".format(token) }
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
#update vendor status
api = f'https://kb.cert.org/vince/comm/api/case/vendor/statement/{case}/'
data = [{'vendor': 3548,
'status':'Not Affected',
'references':["http://www.test.gov", "https://www.google.com"],
'share':True,
'vulnerability':'CVE-2020-19293',
'statement': 'This is my statement'},
{'vendor': 3548,
'status':'Affected',
'statement':"Test",
'references':["http://www.test.gov","https://www.google.com"],
'share':True,
'vulnerability':'VU#785701.2'}]
r = requests.post(api, headers=headers, data=json.dumps(data))
print(r.text)
Code Block
API: /vince/comm/api/vendor #get information about vendors you belong to
[ { 'emails': ['emilytest@gmail.com'], { 'created': '2020-06-11T18:51:48.204903Z',
'due_date': None,
'status': 'Active',
'summary': 'test',
'title': 'test',
'vuid': '782161'},
{ 'created': '2020-04-28T19:48:50.216317Z',
'due_date': '2018-07-23T14:20:09Z',
'status': 'Inactive',
'summary': 'TechSmash firmware or operating system software drivers '
'may not sufficiently validate elliptic curve parameters ''id': 3548,
'users':['emily.sarneso'],
'vendor_name': 'Microsoft'},
'used to generate public keys during a Diffie-Hellman key '
{'emails':['emilytest@gmail.com'],
'id': 3551,
'users': ['emily.sarneso'],
exchange, which may allow a remote attacker to obtain the '
'vendor_name':'TestingCo'},
{ 'emails': ['emilytest@gmail.com', 'emilytest2@gmail.com']encryption key used by the device',
'idtitle': 3549,
'TechSmash implementations may not sufficiently validate '
'users': ['emily.sarneso', 'Emily Ecoff']elliptic curve parameters during Diffie-Hellman key exchange',
'vendor_namevuid': 'Testing Vendor3123125'}]
API:
Get case metadata
Code Block
language
py
# get information about VU#701852
api = 'https://kb.cert.org/vince/comm/api/case/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
language
js
API: vince/comm/api/case/701852/ # get information about a specific case
/cases # get a list of cases involved in
[ { 'created': '2020-06-11T18:51:48.204903Z',
'due_date': None,
'status': 'Active',
'summary': 'test',
'title': 'test',
'vuid': '785701'},
{ 'created': '2020-04-28T19:48:50.216317Z
Get message posts for case
Code Block
language
py
# get all posts for case VU#701852
api = 'https://kb.cert.org/vince/comm/api/case/701852/posts/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
language
js
API: vince/comm/api/case/701852/posts/ # get all posts for a specific case
[ { 'author': 'vince.user',
'due_date': '2018-07-23T14:20:09Z',
'status': 'Inactive',
'summarycontent': 'BluetoothThefirmware or operating system software drivers [draft vulnerability '
'may not sufficiently validate elliptic curve parameters '
note](http://localhost:8000/vince/comm/case/18/notedraft/) '
'hasbeenupdated.'used,
togeneratepublickeysduringaDiffie-Hellman key ' 'created': '2020-11-17T19:13:07.866230Z','pinned':True},
{ 'exchange, which may allow a remote attacker to obtain the '
'author': 'vince.user',
'content': 'Please [view this draft vulnerability '
'encryptionkeyusedbythe device 'note](http://localhost:8000/vince/comm/case/18/notedraft/).',
'titlecreated': 'Bluetooth implementations may not sufficiently validate '2020-11-17T19:07:56.624450Z','pinned':True},
{ 'elliptic curve parameters during Diffie-Hellman key exchange'author': 'vince.user',
'vuidcontent': '304725'}]
API: vince/comm/api/case/701852/ # get information about a specific case
{ test 2',
'created': '2020-0610-11T1829T19:5149:4833.204903Z422875Z',
'due_date 'pinned': NoneFalse},
{ 'statusauthor': 'Activevince.user',
'summarycontent': 'test 1',
'titlecreated': 'test2020-10-29T19:49:30.434164Z',
'vuidpinned': '785701'False}]API: vince/comm/api/case/posts/701852/ # get all posts for a specific case
[ { 'author': 'ecoff',
'content': 'The [draft vulnerability '
'note](http://localhost:8000/vince/comm/case/18/notedraft/) '
'has been updated.',
'created': '2020-11-17T19:13:07.866230Z
Get original report for case
Code Block
language
py
# get the original report for VU#701852
api = 'https://kb.cert.org/vince/comm/api/case/701852/report/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
language
js
API: /vince/comm/case/701582/report/ # get report for a specific case
{ 'contact_email': 'joebob@vendor.example.com',
'contact_name': 'Joe Bob',
'contact_org': 'VendorExample',
'contact_phone': '5551231234',
'date_submitted': '2020-06-08T20:01:47.896419Z',
'pinned'disclosure_plans': True}'',
{ 'authorexploit_references': 'ecoff',
'product_name':'test',
'contentproduct_version': 'v.12.3'Please,
[viewthisdraft vulnerability ' 'public_references': '','share_release':True,
'vendor_name':'TestVendor',
'note](http://localhost:8000/vince/comm/case/18/notedraft/).',
'created': '2020-11-17T19:07:56.624450Z',
'vul_description': 'This is the description',
'pinnedvul_disclose': True},
{ 'authorvul_discovery': 'emily.sarnesoThis is the discovery.',
'content''vul_exploit': 'test 2This is the exploit',
'createdvul_exploited': '2020-10-29T19:49:33.422875Z'True,
'pinned'vul_impact': False},
{ 'author': 'emily.sarneso''This is the impact',
'content'vul_public': 'test 1',
'created': '2020-10-29T19:49:30.434164Z',
'pinned': False}]
API: True}
List vulnerabilities for case
Code Block
language
py
# get the vuls for VU#701852
api = 'https://kb.cert.org/vince/comm/api/case/701852/vuls/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
language
js
API: /vince/comm/case/701582/vulsreport/701582/ # get reportvuls for a specific case
[ { 'contact_emailcve': 'joebob@rapid7.com'None,
'contactdate_nameadded': 'Joe Bob2020-11-19T21:43:17.210726Z',
'contact_orgdescription': 'Rapid 7This is another vul without a cve.',
'contact_phonename': '5551231234VU#785701.2'},
{'date_submittedcve': '2020-06-08T20:01:47.896419Z19293',
'disclosure_plans':'',
'exploitdate_referencesadded': '2020-10-22T15:30:11.888074Z',
'product_name':'test',
'product_versiondescription': 'v. 12.3',
'public_references': '',
'share_release': True,
Test this is a vul.',
'vendor_name': 'Test Vendor',
'vul_description': 'This is the description',
'vul_disclose': True,
'vul_discovery': 'This is the discovery.',
'vul_exploit': 'This is the exploit',
'vul_exploited': True,
'vul_impact': 'This is the impact',
'vul_public': TrueCVE-2020-19293'}]
List vendors for case
Code Block
language
py
# get all the vendors involved in VU#701582 (also gets their status and statements)
api = 'https://kb.cert.org/vince/comm/api/case/701852/vendors/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
language
js
API: /vince/comm/case/701582/vendors/ # get vendors }
API: /vince/comm/case/vuls/701582/ # get vuls for a specific case
[ { 'cvecert_addendum': None,
'date_added': '2020-11-19T2120T14:4340:1724.210726Z080886Z',
'descriptionreferences': 'This is another vul without a cve.http://www.example.com\nhttps://www.example.org',
'namestatement': 'VU#785701.2Test'},
{ 'cvestatement_date': '2020-1929311-23T19:50:44.813809Z',
'date_addedstatus': '2020-10-22T15:30:11.888074ZUnknown',
'descriptionvendor': 'Test this is a vul.'VendorCorp'},
{'namecert_addendum': 'CVE-2020-19293'}]
API: /vince/comm/case/vendors/701582/ # get vendors for a specific case
[ { 'cert_addendum': NoneNone,
'date_added': '2020-1110-20T1408T18:4027:2441.080886Z526942Z',
'references': 'http://www.testexample.govcom\nhttps://www.googleexample.comorg',
'statement': 'Test',
'statement_date': '2020-11-23T1919T21:5026:4432.813809Z399730Z',
'status': 'UnknownAffected',
'vendor': 'Testing Co'}]
List vendors including status and statement for each vulnerability
Code Block
language
py
# get all the vendors and their status/statement/references for each specific vul
api = f'https://kb.cert.org/vince/comm/api/case/701582/vendors/vuls/'
headers={'content-type':'application/json', 'Authorization': "Token {}".format(token) }
r = requests.get(api, headers=headers, stream=True)
print(r.text)
# get the vulnerability note, if available
api = f'https://kb.cert.org/vince/comm/api/case/701582/note'
headers={'content-type':'application/json', 'Authorization': "Token {}".format(token) }
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Code Block
language
js
#API: /vince/comm/api/case/710582/note/ # get draft vul note
{ 'content': '### Overview\r\n'
'\r\n'
note/710582/ # get draft vul note
{ 'content': '### Overview\r\n'
'\r\n'
'Testing API so need some content.\r\n'
'\r\n'
'\r\n'
'### Description\r\n'
'\r\n'
'### Impact\r\n'
'The complete impact of this vulnerability is not yet known.\r\n'
'\r\n'
'### Solution\r\n'
'The CERT/CC is currently unaware of a practical solution to '
'this problem.\r\n'
'\r\n'
'### Acknowledgements\r\n'
'Thanks to the reporter who wishes to remain anonymous.\r\n'
'\r\n'
'This document was written by Emily Sarneso.',
'datefirstpublished': None,
'dateupdated': '2020-11-17T19:13:07.755453Z',
'published': False,
'references': ['www.googleexample.comorg', 'www.testexample.com'],
'revision': 2,
'title': 'test',
'vuid': '785701'}
Update vendor status
Code Block
language
py
#update vendor status
api = f'https://kb.cert.org/vince/comm/api/case/{case}/vendor/statement/{case}/'
data = [{'vendor': 3548,
'status':'Not # vendor ID only required if user belongs to multiple vendors in a case
'status':'Not Affected', # required: ['Affected', 'Not Affected', 'Unknown']
'references':[Affected',
'references':["http://www.test.gov", "https://www.google.com"], #not required, must be a list
'share':True, # not required, default = False
'vulnerability':'CVE-2020-19293', # required - must be in the form 'CVE-xxxx-xxxxx'or 'VU#xxxxxx.n'
'statement': 'This is my statement'}] # not required
OLD JWT WAY: (This doesn't work anymore)
First you have to "login" to get your jwt (JSON web token).
#update vendor status
api = f'https://kb.cert.org/vince/comm/api/case/{case}/vendor/statement/'
data = [{'vendor': 3548, # vendor ID only required if user belongs to multiple vendors in a case
'status':'Not Affected', # required: ['Affected', 'Not Affected', 'Unknown']
'references':["http://www.test.gov", "https://www.google.com"], # not required, must be a list
'share':True, # not required, default = False
'vulnerability':'CVE-2020-19293', # required - must be in the form 'CVE-xxxx-xxxxx' or 'VU#xxxxxx.n'
'statement': 'This is my statement'}] # not required
Look up CVE IDs (must have access to case)
Code Block
# lookup CVE-2021-55555 - must have access to case otherwise 404
api = f'https://kb.cert.org/vince/comm/api/cve/2021-55555/'
headers={'content-type':'application/json', 'Authorization': "Token {}".format(token) }
Code Block
# get a list of your cases
headers={'Authorization': "Bearer {}".format(token)}
api = 'https://vince-test.cert-dit.org/vinny/api/cases/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
# get information about VU#701852
api = 'https://vince-test.cert-dit.org/vinny/api/case/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
# get all posts for case VU#701852
api = 'https://vince-test.cert-dit.org/vinny/api/case/posts/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
# get the original report for VU#701852
api = 'https://vince-test.cert-dit.org/vinny/api/case/report/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
# get the vuls for VU#701852
api = 'https://vince-test.cert-dit.org/vinny/api/case/vuls/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
# get all the vendors involved in VU#701582 (also gets their status and statements)
api = 'https://vince-test.cert-dit.org/vinny/api/case/vendors/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
And if you want to CURL...
Code Block
API: CVE Lookup:
Code Block
curl -X POST -F 'username=[username]' -F 'password=[password]' https://vince-testkb.cert-dit.org/vinnyvince/authcomm/api-token-auth/cve/2021-55555/
{"token":"eyJraWQiOiJ2OXdycTNXXC9FbG9SV2NLanUwNUdRd20wbzgzMm1IUGpVZklEYUcxWUpwaz0iLCJhbGciOiJSUzI1NiJ9.eyJjdXN0b206dGl0bGUiOiJEZXZlbG9wZXIxIiwic3ViIjoiNTM3ZGQ4NjItYWExYy00NDRjLWEzNzMtOWFlNTNjOTZiZTdiIiwiY29nbml0bzpncm91cHMiOlsiQ0VSVFwvQ0MiXSwiZW1haWxfdmVyaWZpZWQiOnRydWUsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTIuYW1hem9uYXdzLmNvbVwvdXMtZWFzdC0yXzFnb2hyTXNIViIsInBob25lX251bWJlcl92ZXJpZmllZCI6dHJ1ZSwiY29nbml0bzp1c2VybmFtZSI6IjUzN2RkODYyLWFhMWMtNDQ0Yy1hMzczLTlhZTUzYzk2YmU3YiIsInByZWZlcnJlZF91c2VybmFtZSI6IkVtaWx5IFNhcm5lc28iLCJnaXZlbl9uYW1lIjoiRW1pbHkiLCJsb2NhbGUiOiJVUyIsImF1ZCI6IjJldGhsZW9nZnVoY2swbDducGFycWhhc3VrIiwiZXZlbnRfaWQiOiIyZGE2N2RjOC00ZGU0LTQyMGMtOWIxYS0zNmM4OGM1YTI3MDkiLCJjdXN0b206T3JnYW5pemF0aW9uIjoiQ0VSVFwvQ0MiLCJ0b2tlbl91c2UiOiJpZCIsImF1dGhfdGltZSI6MTU4MDgyODYxNSwicGhvbmVfbnVtYmVyIjoiKzE0MTI1MTk2NDI2IiwiZXhwIjoxNTgwODMyMjE1LCJpYXQiOjE1ODA4Mjg2MTUsImZhbWlseV9uYW1lIjoiU2FybmVzbyIsImVtYWlsIjoiZWNvZmZAY2VydC5vcmcifQ.bVvX5gNPXoxOY3rgMyb4siY0T6KqR_F4GTiMR-xeGlE3BLuPVL646vsdflsjdlfjsldjfjalfjlajsdla;ldfjtAKp2Tl-6NCeCdJ4utVXpVNLSZ8pUpLclRGI1q--920eieh2O5dugp9tYrXf1D4OuiwMqzAM2MUFwwIFlCJB79O5THXrTtbpmfAp_XNafu94R5kP4VKtiMHd5_vRygPG2eydbCmox6oe1K44sZ1Guc5P4CQ9QYhpT7e8ICscnpKYvHWnnSAdcKguAmCcDPbytJywGohpT7ajxJAmmQRapbaqbHftlipKfkyjWPsxE0X3v8Uf-_WZG7z9yZjxdeeB-EP_V7z2WRoay8mWhjxJjCVHHbaxlqDA","email":"ecoff@cert.org"}
curl https://vince-test.cert-dit.org/vinny/api/case/report/701852/ -H 'Accept: application/json' -H 'Authorization: Bearer eyJraWQiOiJ2OXdycTNXXC9FbG9SV2NLanUwNUdRd20wbzgzMm1IUGpVZklEYUcxWUpwaz0iLCJhbGciOiJSUzI1NiJ9.eyJjdXN0b206dGl0bGUiOiJEZXZlbG9wZXIxIiwic3ViIjoiNTM3ZGQ4NjItYWExYy00NDRjLWEzNzMtOWFlNTNjOTZiZTdiIiwiY29nbml0bzpncm91cHMiOlsiQ0VSVFwvQ0MiXSwiZW1haWxfdmVyaWZpZWQiOnRydWUsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTIuYW1hem9uYXdzLmNvbVwvdXMtZWFzdC0yXzFnb2hyTXNIViIsInBob25lX251bWJlcl92ZXJpZmllZCI6dHJ1ZSwiY29nbml0bzp1c2VybmFtZSI6IjUzN2RkODYyLWFhMWMtNDQ0Yy1hMzczLTlhZTUzYzk2YmU3YiIsInByZWZlcnJlZF91c2VybmFtZSI6IkVtaWx5IFNhcm5lc28iLCJnaXZlbl9uYW1lIjoiRW1pbHkiLCJsb2NhbGUiOiJVUyIsImF1ZCI6IjJldGhsZW9nZnVoY2swbDducGFycWhhc3VrIiwiZXZlbnRfaWQiOiIyZGE2N2RjOC00ZGU0LTQyMGMtOWIxYS0zNmM4OGM1YTI3MDkiLCJjdXN0b206T3JnYW5pemF0aW9uIjoiQ0VSVFwvQ0MiLCJ0b2tlbl91c2UiOiJpZCIsImF1dGhfdGltZSI6MTU4MDgyODYxNSwicGhvbmVfbnVtYmVyIjoiKzE0MTI1MTk2NDI2IiwiZXhwIjoxNTgwODMyMjE1LCJpYXQiOjE1ODA4Mjg2MTUsImZhbWlseV9uYW1lIjoiU2FybmVzbyIsImVtYWlsIjoiZWNvZmZAY2VydC5vcmcifQ.bVvX5gNPXoxOY3rgMyb4siY0T6KqR_F4GTiMR-xeGlE3BLuPVL646vtAKp2Tl-6NCeCdJ4udsfsdfsdfsdfsfsdtVXpVNLSZ8pUpLclRGI1q--920eieh2O5dugp9tYrXf1D4OuiwMqzAM2MUFwwIFlCJB79O5THXrTtbpmfAp_XNafu94R5kP4VKtiMHd5_vRygPG2eydbCmox6oe1K44sZ1Guc5P4CQ9QYhpT7e8ICscnpKYvHWnnSAdcKguAmCcDPbytJywGohpT7ajxJAmmQRapbaqbHftlipKfkyjWPsxE0X3v8Uf-_WZG7z9yZjxdeeB-EP_V7z2WRoay8mWhjxJjCVHHbaxlqDA'
{"vendor_name":"AwesomeTools","product_name":"AwesomeTools Library v.1.2.3","product_version":"v.1.2.3","vul_description":"Buffer Overflow","vul_exploit":"Populate library data structure with string field with 10000 characters","vul_impact":"Code execution","vul_discovery":"Fuzzing","vul_public":false,"public_references":"","vul_exploited":false,"exploit_references":"","vul_disclose":false,"disclosure_plans":"","date_submitted":"2020-01-27T15:25:24.028635Z","share_release":true,"contact_name":"Emily Smith3w","contact_phone":"","contact_email":"emilysmith42675-usability3@yahoo.com","contact_org":"Usability"}
# get a list of your cases
api = 'https://[VINCE_URL]/comm/api/cases/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Retrieve a specific case
Code Block
# get information about VU#701852
api = 'https://[VINCE_URL]/comm/api/case/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Retrieve posts for a case
Code Block
# get all posts for case VU#701852
api = 'https://[VINCE_URL]/comm/api/case/posts/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Retrieve original report for a case
Code Block
# get the original report for VU#701852
api = 'https://[VINCE_URL]/comm/api/case/report/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Retrieve vuls for a case
Code Block
# get the vuls for VU#701852
api = 'https://[VINCE_URL]/comm/api/case/vuls/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text)
Retrieve vendors for a case
Code Block
# get all the vendors involved in VU#701582 (also gets their status and statements)
api = 'https://[VINCE_URL]/comm/api/case/vendors/701852/'
r = requests.get(api, headers=headers, stream=True)
print(r.text){ 'case': { 'created': '2020-03-11T18:56:14.975973Z',
'due_date': '2020-03-25T0000Z',
'status': 'Active',
'summary': 'This is a summary',
'title': 'This is a title',
'vuid': '123456'},
'note': 'NOT Public',
'vendors': [ { 'references': '',
'statement': '',
'statement_date': '2020-11-20T11:05:07.603524Z',
'status': 'Unknown',
'vendor': 'Test Vendor',
'vulnerability': 'CVE-2021-55555'}],
'vulnerability': { 'cve': '2021-55555',
'date_added': '2020-03-11T20:37:51.629151Z',
'description': 'This is a description of the vulnerability',
'name': 'CVE-2021-55555'}}