API Functionality

[ZeroSums]

The SO Documentation doesn't mention an API that is available, which is a feature that could be very useful for the community. Some folks mentioned this & this back in 2021. However, as of the time of writing (2024) we have no API yet. I understand & empathize this request likely falls low on the cost-benefit tree. But I do have some use-cases and some compromises that could be made if an API is not possible for the foreseeable future.

For instance, some example use-cases:

1. Return a specific dashboards values, let's use the 'Source Countries' Dashboard for our example. I want to return all IPs from a specific Source Country. It would be ideal to construct an API request which would return the IPs from that source country.
2. Logging in via a Bearer Token

Benefits:

1. Allows SO to be extended into other applications.
2. Allows other developers to ingest data into other applications, such as Prometheus. (Would be awesome to track metrics of Alerts, Logins, Traffic, etc)

Compromises:

1. Release some documentation on how login authentication occurs and what is required for logging in. Presently, those documents do not exist, and one would have to reverse engineer SO to figure out how it works. (Which is time consuming for users).
2. Introduce a config param in /#/config which allows specific users to login without a password (Caveat could be, this user is unable to have super-admin permissions and only analyst?) . This would bypass the headache of authentication while mitigating risks.

For context, to merely login, a seemingly complicated process takes place. Within the /#/ route, where the login fields are, when you fill those out and login, a few things happen:

1. The request is constructed with a unique query string flow=xx11xx11-x1xx-1234-xxx1-x1x111xx1x11
2. A POST request is sent to the route with our unique query string: /auth/self-service/login?flow=xx11xx11-x1xx-1234-xxx1-x1x111xx1x11 with the Form Data:
   a. 'identifier' (SO E-Mail)
   b. 'password' (self explanatory)
   c. csrf_token (self explanatory)
   d. 'method' (Method of SO login which in our case will be method: password)
3. The response returns as 303

However. if I attempt to send a typical POST request via postman or PHP Guzzle, to the /#/ route attempting to login, it fails. Likely, because I'm unable to construct the request with our unique query string, which is not documented on how it is constructed, is it random, is it semi random - semi unique? These are the things which should be documented, if SO chooses to provide insight on the authentication process.

However, I wrote a python script which extends selenium to open a headless chrome session. I will provide the logic, incase others have/want to create their own ad-hoc janky API without spending the time overcoming the authentication obstacle:

self.driver.get(website_url)
            ## We wait for the form field "password_identifier" to show up (which is what's used for the e-mail)
            WebDriverWait(self.driver, 10).until(EC.visibility_of_element_located((By.ID, "password_identifier")))
            ## We tell selenium to type our SO e-mail (which is stored in an .env file)
            self.driver.find_element(By.ID, "password_identifier").send_keys(website_username)
            ## We tell selenium to type our SO password (which is stored in an .env file)
            self.driver.find_element(By.ID, "input-27").send_keys(website_password)
            ## We virtually hit our enter key to login
            self.driver.find_element(By.ID, "input-27").send_keys(Keys.ENTER)
            ## Wait for the user icon in the top right, as a sanity check we're actually logged in.
            WebDriverWait(self.driver, 10).until(EC.presence_of_element_located((By.CSS_SELECTOR, ".fa-user")))
            logging.info("Logged in successfully!")

I value the hard-work the SO team has put into this product and I hope to have a fruitful discussion regarding the things I have mentioned above.
Furthermore, if any other Devs come here seeking an API, as it stands right now, using selenium to login is the only approach which is Plug-n-Play. Feel free to use the code-sample above. I may just release my prometheus exporter for Security Onion on my Github for the public use.