Package: pysnyk
pysnykA Python client for theSnyk API.ClientUsing the client requires you to provide your Snyk API token.importsnykclient=snyk.SnykClient("<your-api-token>")By default the client will connect to the public Snyk service. If you are using a local installation then you can provide the API url as the second argument.importsnykclient=snyk.SnykClient("<your-api-token>","<your-instance-of-snyk>")By default theUser-Agentstring for the API requests will bepysnyk/<version>. If you would like to send a custom user agent you can do so as follows:importsnykclient=snyk.SnykClient("<your-api-token>",user_agent="<your-instance-of-snyk>")By default the requests are not retried. If you would like to retry failed requests withbackoffanddelayyou can do so as follows:importsnykclient=snyk.SnykClient("<your-api-token>",tries=4,delay=1,backoff=2)tries- the maximum number of attempts.Default:1(no retries)delay- initial delay between attempts.Default:1backoff- multiplier applied to delay between attempts.Default:2debug- run client in debug mode, useful for debugging API requests.Default:FalseOrganizationsWith the client we can get a list of Snyk organizations you are a member of:client.organizations.all()This returns a list ofsnyk.models.Organizationobjects.If you already have the ID of the organization you're after you can grab it directly:client.organizations.get("<organization-id>")This will return a singlesnyk.models.Organizationobject.Most of the API is scoped to organizations, so most other methods are found on thesnyk.models.Organizationobjects returned by these two methods.Thesnyk.models.Organizationobject has the following properties related to the API:entitlements- returns the set of Snyk features available to this accountdependencies- returns a Manager for packages in use in this organizationlicenses- returns a Manager for licenses currently in use by projects in this organisationmembers- returns a Manager for membersprojects- returns a Manager for associated projectsintegrations- returns a Manager for active integrationsA note on ManagersManagers provide a consistent API for accessing objects from the Snyk API. Each manager implements the following methods:all()- return a list of all of the relevant objectsget("<id>")- return a single instance of the object if it existsfirst()- grab the first instance of the object if one existsfilter(<key>="<value>")- return a list filtered by one or more key/value pairsProjectsOnce you have an organization you're likely to want to grab the related projects:client.organizations.first().projects.all()This will return a list ofsnyk.models.Projectobjects.In the case where you want to get all of the projects across all of your organizations then you can use the handy method on the client.client.projects.all()Thesnyk.models.Projectobject has the following useful properties and methods:delete()- deletes the project in question. Be careful as this will delete all associated data toomove(new_org_id)- moves the project to a new organizationdependencies- returns a Manager for packages in use in this projectdependency_graph- returns asnyk.models.DependencyGraphobject which represents the full dependency graph of package dependenciesignores- returns a Manager for ignore rules set on the projectvulnerabilities- returns a list ofsnyk.models.Vulnerabilityobjects with information about vulnerabilities in this projectjira_issues- returns a Manager with access to any associated Jira issueslicenses- returns a Manager for licenses currently in use by this projectsettings- returns a Manager for interacting with the current project settingstags- returns a Manager for interacting with the current project tagsYou can add and delete tags using the manager:tags.add(key, value)- adds a tag with the provided key/value pair to the projecttags.delete(key, value)- deletes a tag with the provided key/value pair from the projectIn the case of Projects, as well as filtering by properties (as mentioned above) you can also filter by tag:client.organizations.first().projects.filter(tags=[{"key":"some-key","value":"some-value"}])Note that thesettingsManager can also be used to update settings like so, assuming you have asnyk.models.Projectobject in the variableproject.project.settings.update(pull_request_test_enabled=True)Importing new projectsThe client supports a high-levelimport_projectmethod on organizations for adding new projects to be monitored by Snyk.org=client.organizations.first()org.import_project("github.com/user/project@branch")org.import_project("docker.io/repository:tag")If you are targetting a specific manifest file or files you can pass those as an optional argument, for instance:org.import_project("github.com/user/project@branch",files=["Gemfile.lock"])This method currently only supports importing projects from GitHub and Docker Hub. For other integrations you will need to grab the lower-levelsnyk.models.Integrationobject from thesnyk.models.Organization.integrationsmanager noted above. Other services will be added to this API soon.Testing for vulnerabilitiesThe API also exposes methods to discover vulnerability information about individual packages. These methods are found on the Organization object.test_maven(<package_group_id>, <package_artifact_id>, <version>)- returns an IssueSet containing vulnerability information for a Maven artifacttest_rubygem(<name>, <version>)- returns an IssueSet containing vulnerability information for a Ruby Gemtest_python(<name>, <version>)- returns an IssueSet containing vulnerability information for Python package from PyPitest_npm(<name>, <version>)- returns an IssueSet containing vulnerability information for an NPM packageHere's an example of checking a particular Python package.>>>org=client.organizations.first()>>>result=org.test_python("flask","0.12.2")>>>assertresult.okFalse# You can access details of the vulnerabilities too, for example>>>result.issues.vulnerabilities[0].title'Improper Input Validation'>>>result.issues.vulnerabilities[0].identifiers{'CVE':['CVE-2018-1000656'],'CWE':['CWE-20']As well as testing individual packages you can also test all packages found in various dependency management manifests. The client currently supports the following methods:test_pipfile(<file-handle-or-string>)- returns an IssueSet for all Python dependencies in aPipfiletest_gemfilelock(<file-handle-or-string>)- returns an IssueSet for all Ruby dependencies in aGemfiletest_packagejson(<file-handle-or-string>, (<lock-file-handle-or-string>))- returns an IssueSet for all Javascript dependencies in apackage.jsonfile. Optionally takes apackage.lockfiletest_gradlefile(<file-handle-or-string>)- returns an IssueSet for all dependencies in aGradlefiletest_sbt(<file-handle-or-string>)- returns an IssueSet for all dependencies defined in a.sbtfiletest_pom(<file-handle-or-string>)- returns an IssueSet for all dependencies in a Mavenpom.xmlfiletest_yarn(<file-handle-or-string>, <lock-file-handle-or-string>)- returns an IssueSet for all dependencies in Yarnpackage.jsonandyarn.lockfilestest_composer(<file-handle-or-string>, <lock-file-handle-or-string>)- returns an IssueSet for all dependencies in Composercomposer.jsonandcomposer.lockfilesFor example, here we are testing a PythonPipfile.>>>org=client.organizations.first()>>>file=open("Pipfile")>>>org.test_pipfile(file)Inviting new usersYou can invite new users to the organization via the API.>>>org=client.organizations.first()>>>org.invite("example@example.com")You can also invite new users as administrators:>>>org=client.organizations.first()>>>org.invite("example@example.com",admin=True)Low-level clientAs well as the high-level API of the Snyk client you can use the HTTP methods directly. For these you simply need to pass the path, and optionally a data payload. The full domain, and the authentication details, are already provided by the client.client.get("<path>")client.delete("<path>")client.put("<path>",<data>)client.post("<path>",<data>)Most of the time you shouldn't need to use these. They are mainly useful if new methods are added to the API which are not yet supported in the client. This can also be useful if you want to pass very specific parameters, or to parse the raw JSON output from the API.Experimental rest low-level clientpysnyk >= 0.9.0 now includes support for basic rest (formerly referred to as v3) compatibility. To switch to use a rest client, pass the rest API url and version when initializing a client. Right now it supports theGETmethod. Refer to therest API docsfor more information and examples.Getting the rest information of an organization:# To get this value, get it from a Snyk organizations settings pagesnyk_org="df734bed-d75c-4f11-bb47-1d119913bcc7"# to use the rest endpoint you MUST include a version value and the url of the v3 api endpoint as shown belowrest_client=SnykClient(snyk_token,version="2022-02-16~experimental",url="https://api.snyk.io/rest")print(rest_client.get(f"/orgs/{snyk_org}").json())# this supports overriding rest versions for a specific GET requests:user=rest_client.get(f"orgs/{snyk_org}/users/{snyk_user}",version="2022-02-01~experimental").json()# pass parameters such as how many results per pageparams={"limit":10}targets=rest_client.get(f"orgs/{snyk_org}/targets",params=params)V1 and rest can work at the same time by instantiating two clients:snyk_org="df734bed-d75c-4f11-bb47-1d119913bcc7"v1client=SnykClient(snyk_token)rest_client=SnykClient(snyk_token,version="2022-02-16~experimental",url="https://api.snyk.io/rest")v1_org=v1client.organizations.get(snyk_org)rest_org=rest_client.get(f"/orgs/{snyk_org}").json()The rest API introduces consistent pagination across all endpoints. The v3 client includes a helper method.get_rest_pageswhich collects the paginated responses and returns a single list combining the contents of the "data" key from all pages. It takes the same values as the get method.rest_client=SnykClient(snyk_token,version="2022-02-16~experimental",url="https://api.snyk.io/rest")params={"limit":10}targets=rest_client.get(f"orgs/{snyk_org}/targets",params=params).json()print(len(targets["data"]))# returns 10 targetsall_targets=rest_client.get_rest_pages(f"orgs/{snyk_org}/targets",params=params)print(len(all_targets))# returns 33 targets, note we don't have to add .json() to the call or access the "data" key, get_rest_pages does that for us# Override Content-Type header (or others) as needed forresponse=rest_client.post(f"orgs/{snyk_org}/invites",body={"email":"some.body@snyk.io","role":"f8223479-01a9-4774-8e29-06ce9a0513d6",headers={"Content-Type":"application/vnd.api+json"}})For backwards compatibility the get_rest_pages method has an alternative name of get_v3_pages to not break code already rewritten replatformed to the 0.9.0 pysnyk module.