5. API Reference - openphish/pyopdb GitHub Wiki

The OPDB API provides the following methods that you can use as part of your tools.

class pyopdb.OPDB

An OPDB management object has the following methods:

update()

Downloads the most recent version of the DB and stores it at the location specified by local_db_path in the configuration file. The method checks if a new version of the database exists and performs integrity checks before overriding the local db. Note: the method overrides the existing local copy of the database.

Example:

import pyopdb
opdb = pyopdb.OPDB(cfg_file=<CONFIG_PATH>)
print(opdb.update())

{'success': True, 'message': 'DB is up to date', 'data': None}

run_query(q: str, *args)

Runs a custom SQL query and returns the raw results. Use the args argument to pass values when a qmark style is used in the SQL query (see https://docs.python.org/3/library/sqlite3.html)

Example:

import pyopdb
opdb = pyopdb.OPDB(cfg_file=<CONFIG_PATH>)
print(opdb.run_query("SELECT count(distinct url) FROM phishing_urls WHERE asn=?", "AS22612"))

{'success': True, 'message': None, 'data': [(3645,)]}

print(db.run_query("SELECT ip FROM phishing_urls WHERE brand='WhatsApp'"))

{'success': True, 'message': None, 'data': [('178.18.252.XX',), ('149.28.151.XX',), ...]}

Module Functions

pyopdb.check_url(opdb: OPDB, url: str)

Performs an exact match for a given URL. Input URL must start with http or https. The method normalizes the URL before querying the database. The method returns the discovery timestamp and the targeted brand name in the data key of the response.

Example:

import pyopdb
opdb = pyopdb.OPDB(cfg_file=<CONFIG_PATH>)
print(pyopdb.check_url(opdb, "http://example.com/"))

{'success': True, 'message': 'Not a phishing URL', 'data': None}

pyopdb.check_ip(opdb: OPDB, ip: str)

Performs an exact search for a given IPv4 in the database. The method returns a list of distinct URLS associated with the IPv4 address.

Example:

import pyopdb
opdb = pyopdb.OPDB(cfg_file=<CONFIG_PATH>)
print(pyopdb.check_ip(opdb, "8.8.8.8"))

{'success': True, 'message': 'No phishing URLs', 'data': None}

pyopdb.check_hostname(opdb: OPDB, hostname: str)

Performs a fuzzy match (SQL ‘LIKE’) to check for phishing URLs on a hostname. The method will return a list of distinct hostnames found.

Example:

import pyopdb
opdb = pyopdb.OPDB(cfg_file=<CONFIG_PATH>)
print(pyopdb.check_hostname(opdb, "web.app"))

{'success': True, 'message': None, 'data': {'hosts': ['***.web.app', '****.web.app', '****.web.app', ...]}}

pyopdb.prepare_url(url: str)

Performs normalization of a given URL. Use this method on a URL before running any custom query that uses the url_norm field.

Example:

import pyopdb

print(pyopdb.prepare_url("http://example.com/index.html"))
http://example.com/

print(pyopdb.prepare_url("http://example.com/index.html?id=1"))
http://example.com/

print(pyopdb.prepare_url("https://example.com/a.html?id=1#a"))
https://example.com/a.html

print(pyopdb.prepare_url("http://example.com/subdir/¢-symbol"))
http://example.com/subdir/%C2%A2-symbol/

print(pyopdb.prepare_url("hxxp://example.com/"))
None

print(pyopdb.prepare_url("http://б.com/specialchar"))
http://xn--90a.com/specialchar/