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 feedback through VINCE.
NEW Token Authentication:
First, you have to login to the VINCE COMM UI and generate a key in your profile:
Copy the key to a safe place, you won't be able to access it again. You will have to regenerate the key if you lose it.
Use the token in the headers of your requests. Notice the change from "Bearer" to "Token."
Code Examples
Edits in progress. This note will be removed when the page is stable. - Allen D. Householder
# 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)
# 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)
# 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)
# 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)
# 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)
# 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)
# 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 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, stream=True)
print(r.text)
# get the vulnerability note, if available
api = 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)
#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)
API: /vince/comm/api/vendor #get information about vendors you belong to
[ { 'emails': ['emilytest@gmail.com'],
'id': 3548,
'users': ['emily.sarneso'],
'vendor_name': 'Microsoft'},
{ 'emails': ['emilytest@gmail.com'],
'id': 3551,
'users': ['emily.sarneso'],
'vendor_name': 'Testing Co'},
{ 'emails': ['emilytest@gmail.com', 'emilytest2@gmail.com'],
'id': 3549,
'users': ['emily.sarneso', 'Emily Ecoff'],
'vendor_name': 'Testing Vendor'}]
API: /vince/comm/api/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',
'due_date': '2018-07-23T14:20:09Z',
'status': 'Inactive',
'summary': 'Bluetooth firmware or operating system software drivers '
'may not sufficiently validate elliptic curve parameters '
'used to generate public keys during a Diffie-Hellman key '
'exchange, which may allow a remote attacker to obtain the '
'encryption key used by the device',
'title': 'Bluetooth implementations may not sufficiently validate '
'elliptic curve parameters during Diffie-Hellman key exchange',
'vuid': '304725'}]
API: vince/comm/api/case/701852/ # get information about a specific case
{ 'created': '2020-06-11T18:51:48.204903Z',
'due_date': None,
'status': 'Active',
'summary': 'test',
'title': 'test',
'vuid': '785701'}
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',
'pinned': True},
{ 'author': 'ecoff',
'content': 'Please [view this draft vulnerability '
'note](http://localhost:8000/vince/comm/case/18/notedraft/).',
'created': '2020-11-17T19:07:56.624450Z',
'pinned': True},
{ 'author': 'emily.sarneso',
'content': 'test 2',
'created': '2020-10-29T19:49:33.422875Z',
'pinned': False},
{ 'author': 'emily.sarneso',
'content': 'test 1',
'created': '2020-10-29T19:49:30.434164Z',
'pinned': False}]
API: /vince/comm/case/report/701582/ # get report for a specific case
{ 'contact_email': 'joebob@rapid7.com',
'contact_name': 'Joe Bob',
'contact_org': 'Rapid 7',
'contact_phone': '5551231234',
'date_submitted': '2020-06-08T20:01:47.896419Z',
'disclosure_plans': '',
'exploit_references': '',
'product_name': 'test',
'product_version': 'v. 12.3',
'public_references': '',
'share_release': True,
'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': True}
API: /vince/comm/case/vuls/701582/ # get vuls for a specific case
[ { 'cve': None,
'date_added': '2020-11-19T21:43:17.210726Z',
'description': 'This is another vul without a cve.',
'name': 'VU#785701.2'},
{ 'cve': '2020-19293',
'date_added': '2020-10-22T15:30:11.888074Z',
'description': 'Test this is a vul.',
'name': 'CVE-2020-19293'}]
API: /vince/comm/case/vendors/701582/ # get vendors for a specific case
[ { 'cert_addendum': None,
'date_added': '2020-11-20T14:40:24.080886Z',
'references': 'http://www.test.gov\nhttps://www.google.com',
'statement': 'Test',
'statement_date': '2020-11-23T19:50:44.813809Z',
'status': 'Unknown',
'vendor': 'Microsoft'},
{ 'cert_addendum': None,
'date_added': '2020-10-08T18:27:41.526942Z',
'references': 'http://www.test.gov\nhttps://www.google.com',
'statement': 'Test',
'statement_date': '2020-11-19T21:26:32.399730Z',
'status': 'Affected',
'vendor': 'Testing Co'}]
API: /vince/comm/case/vendors/vuls/701582/ # get vendors status for specific vuls
[ { 'references': 'http://www.test.gov\nhttps://www.google.com',
'statement': 'Test',
'statement_date': '2020-11-19T21:47:44.239683Z',
'status': 'Affected',
'vendor': 'Testing Co',
'vulnerability': 'VU#785701.2'},
{ 'references': 'http://www.test.gov\nhttps://www.google.com',
'statement': 'This is my statement',
'statement_date': '2020-10-22T15:38:11.859615Z',
'status': 'Not Affected',
'vendor': 'Testing Co',
'vulnerability': 'CVE-2020-19293'},
{ 'references': '',
'statement': '',
'statement_date': '2020-11-20T15:23:18.997947Z',
'status': 'Unknown',
'vendor': 'Microsoft',
'vulnerability': 'VU#785701.2'},
{ 'references': '',
'statement': '',
'statement_date': '2020-11-20T15:23:18.938232Z',
'status': 'Unknown',
'vendor': 'Microsoft',
'vulnerability': 'CVE-2020-19293'}]
#API: /vince/comm/api/case/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.google.com', 'www.test.com'],
'revision': 2,
'title': 'test',
'vuid': '785701'}
#update vendor status
api = f'https://kb.cert.org/vince/comm/api/case/vendor/statement/{case}/'
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
OLD JWT WAY: (This doesn't work anymore)
First you have to "login" to get your jwt (JSON web token).
url = 'https://vince-test.cert-dit.org/vinny/auth/api-token-auth/'
r = requests.post(url, data={'username':user, 'password':password})
rj = r.json()
token = rj['token']
Examples:
# 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...
curl -X POST -F 'username=[username]' -F 'password=[password]' https://vince-test.cert-dit.org/vinny/auth/api-token-auth/
{"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"}
Items below this line are older API docs
Getting an Authentication Token
- Log in to VINCE.
- Go to your User Profile.
- Scroll down to "Generate API Key".
- Copy they API key to a safe place, you will not be able to access it again. If lost, you need to regenerate a new one.
Using the token
headers={'Authorization': "Token {}".format(token)}
API Reference
List cases
# 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
# 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
# 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
# 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
# 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
# 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)