Frontend API Reference

restapi

Public REST API for SightHouse clients

Classes:

FrontendRestAPI –

REST API server for SightHouse public API

Functions:

admin_required –

Restrict a route to logged-in administrators
build_analysis_databases –

Turn a list of BSIM/FIDB URIs into the analyzer's databases entries.
get_current_user –

Wrapper function so mypy stop yelling at me

FrontendRestAPI

FrontendRestAPI(database: FrontendDatabase, logger: Logger)

Bases: ServerThread

REST API server for SightHouse public API

Parameters:

app
(Flask) –

The Flask application instance that this server will host.
host
(str) –

The host address (e.g., '127.0.0.1' or '0.0.0.0') on which the server will listen for incoming requests.
port
(int) –

The port number (typically between 1024 and 65535) on which the server will accept connections.

Methods:

run –

Starts the HTTP server, listening for incoming requests
shutdown –

Shuts down the running server gracefully.

Attributes:

host (str) –

Return the address on which this server is listening
port (int) –

Return the port on which the server is listening

Source code in sighthouse/frontend/restapi.py

def __init__(
    self,
    database: FrontendDatabase,
    logger: Logger,
):
    self.__config = database.get_config()
    self.__database: FrontendDatabase = database
    self.__logger = logger
    self.__app = Flask(__name__, static_url_path="", static_folder="web")
    self.__app.secret_key = token_hex(32)
    self.__register_routes()
    self.__register_error_handlers()
    self.__login_manager = LoginManager()
    self.__login_manager.init_app(self.__app)
    self.__register_user_stuff()
    self.__languages_cache: Optional[List[str]] = (
        None  # lazily-filled Ghidra language list
    )
    self.__celery_app = Celery(
        "", broker=self.__config.worker_url, backend=self.__config.worker_url
    )
    self.__static_dir = Path(self.__app.root_path) / "web"

    super().__init__(self.__app, self.__config.host, self.__config.port)

host `property`

host: str

Return the address on which this server is listening

port `property`

port: int

Return the port on which the server is listening

run

run() -> None

Starts the HTTP server, listening for incoming requests and serving the Flask application.

Source code in sighthouse/core/utils/api.py

def run(self) -> None:
    """Starts the HTTP server, listening for incoming requests
    and serving the Flask application."""
    self.__server.serve_forever()

shutdown

shutdown() -> None

Shuts down the running server gracefully.

Source code in sighthouse/core/utils/api.py

def shutdown(self) -> None:
    """Shuts down the running server gracefully."""
    self.__server.shutdown()

admin_required

admin_required(f)

Restrict a route to logged-in administrators

Source code in sighthouse/frontend/restapi.py

def admin_required(f):
    """Restrict a route to logged-in administrators"""

    @wraps(f)
    @login_required
    def wrapper(*args, **kwargs):
        if not get_current_user().is_admin():
            abort(403)
        return f(*args, **kwargs)

    return wrapper

build_analysis_databases

build_analysis_databases(urls: List[str]) -> List[dict]

Turn a list of BSIM/FIDB URIs into the analyzer's databases entries.

Source code in sighthouse/frontend/restapi.py

def build_analysis_databases(urls: List[str]) -> List[dict]:
    """Turn a list of BSIM/FIDB URIs into the analyzer's ``databases`` entries."""
    databases = []
    for e in (parse_uri(u) for u in urls):
        url = (
            f"{e['type']}://{e['host']}:{e['port']}/{e['dbname']}"
            if "dbname" in e
            else str(e["database"])
        )
        databases.append(
            {"url": url, "user": e.get("user", ""), "password": e.get("password") or ""}
        )
    return databases

get_current_user

get_current_user() -> User

Wrapper function so mypy stop yelling at me

Source code in sighthouse/frontend/restapi.py

def get_current_user() -> User:
    """Wrapper function so mypy stop yelling at me"""
    # Cast LocalProxy to user
    return cast(User, current_user)

Public REST API

Here is the documentation for the REST API of the frontend.

GET /api/v1/setup

›

Setup check endpoint

Responses

Code	Description
200	successful operation { "need_setup": <True / False> }

POST /api/v1/setup

›

Perform setup endpoint

Parameters

Name	Type	Description
user	User	First user to create as admin

Responses

Code

Description

200

successful operation

{
     "success": "Setup successful"
 }

400

Invalid user/password value

{
   "error": "Missing user or password"
}

500

Internal server error

{
   "error": "Fail to add user to database"
}

GET /api/v1/users

›

Return the list of users without their password hash

Responses

Code	Description
200	Successful operation { "users": [{ "id": 1234, "name": "test", "role": "user" }, {...}] }

POST /api/v1/users

›

Add a new user in the database

Responses

Code

Description

201

Successful operation

{
   "success": "User was added"
}

400

Invalid user/password value

{
   "error": "Missing user or password"
}

500

Internal server error

{
   "error": "Fail to add user to database"
}

DELETE /api/v1/users

›

Delete a user, revoke the session if an administrator deletes itself

Responses

Code

Description

200

Successful operation

{
   "success": "User was deleted"
}

400

Invalid parameters or last administrator

{
   "error": "Missing user"
}

500

Internal server error

{
   "error": "Fail to delete user to database"
}

PUT /api/v1/users

›

Update a user role or password in the database

Responses

Code

Description

200

Successful operation

{
   "success": "User was updated"
}

400

Invalid user/password value

{
   "error": "Missing user/role/password"
}

500

Internal server error

{
   "error": "Fail to update user in database"
}

GET /api/v1/config

›

Get the server configuration

Responses

Code	Description
200	Successful operation { "configuration": { "version": "1.0.0", "host": "0.0.0.0", ... } }

PUT /api/v1/config

›

Update (partially) the frontend configuration

Responses

Code

Description

200

Successful operation

{
   "configuration": {...},
   "restart_required": ["port", ...]
}

400

Invalid parameters

{
   "error": "port must be between 1024 and 65535"
}

POST /api/v1/restart

›

Restart the server to apply restart-only configuration changes. Requires the SIGHUP handler installed by `frontend start`.

Responses

Code

Description

200

the server is restarting

{
    "success": "Server is restarting"
}

501

restart is not supported in this environment

{
    "error": "Restart is not supported in this environment"
}

GET /api/v1/ping

›

Health check endpoint

Responses

Code	Description
200	successful operation { "success": "Pong !" }

POST /api/v1/login

›

Login endpoint

Parameters

Name	Type	Description
user	str	The username for the login
password	str	The password for the login

Responses

Code

Description

200

Successful operation

{
   "success": "Login successful"
}

400

Invalid user/password value

{
   "error": "Missing user or password"
}

401

Invalid credentials

{
   "error": "Invalid credentials"
}

POST /api/v1/logout

›

Logout endpoint

Responses

Code	Description
200	Successful operation { "success": "Login successful" }

GET /api/v1/me

›

Get current user informations endpoint

Responses

Code	Description
200	Successful operation { "user": { "id": 1234, "name": "test", "role": "user" } }

GET /api/v1/languages

›

List languages supported by the analyzer

Responses

Code	Description
200	Successful operation { "languages": ["ARM", ...] }

POST /api/v1/uploads

›

Endpoint for upload files into the server

Parameters

Name	Type	Description
filename	str, bytes	Multipart encoded file to upload

Responses

Code

Description

200

Successful operation

{
   "success": "File uploaded",
   "file: 1234
}

400

Invalid parameters

{
   "error": "Missing 'filename' field in upload data"
}

500

Internal server error

{
   "error": "Fail to add file to database"
}

GET /api/v1/uploads

›

List the files uploaded on the server

Responses

Code	Description
200	Successful operation { "files: [{ "id": 1234, "name": "ls.bin", "user": 5678, "hash": "9fed8..." }, {...}] }

DELETE /api/v1/uploads/<string:hash>

›

Endpoint for deleting files from the upload server

Parameters

Name	Type	Description
hash	str	hash of the file to delete

Responses

Code

Description

200

Successful operation

{
   "success": "File deleted"
}

404

Invalid parameters

{
   "error": "The given file does not exists"
}

500

Internal server error

{
   "error": "Fail to delete file from database"
}

POST /api/v1/programs

›

Endpoint for creating new programs in the system.

Parameters

Name	Type	Description
programs	list[program]	A list of JSON program to create

Responses

Code

Description

201

Successful operation

{
   "programs": [<list of created program>]
}

400

Bad request for missing or invalid parameters

{
   "error": "Invalid program data in program list"
}

GET /api/v1/programs

›

Endpoint for retrieving all programs associated with the current user.

Responses

Code	Description
200	Successfully retrieved user programs { "programs": [{"id": 1234, "name": "ls.bin", ...}, {...}] }

GET /api/v1/programs/<int:program_id>

›

Endpoint for retrieving a specific program by its ID.

Parameters

Name	Type	Description
program_id	int	ID of the requested program
recursive	str	A string corresponding to a boolean (either 'true' or 'false') that tell the server to return the program sub elements such as functions.

Responses

Code

Description

200

Successfully retrieved the program

{
    "id": 1234,
    "name": "ls.bin",
    "user": 4567,
    "language": "x86_64",
    "file": 2468,
}

404

Program not found

{
   "error": "Program not found"
}

DELETE /api/v1/programs/<int:program_id>

›

Endpoint for deleting a specific program by its ID.

Parameters

Name	Type	Description
program_id	int	ID of the program to delete

Responses

Code	Description
200	Successful operation { "success": "Program deleted" }
403	Forbidden if the program is under analysis { "error": "Cannot modify program while it is being analyzed" }
404	Program not found { "error": "Program not found" }
500	Internal server error if deletion fails { "error": "Fail to delete program" }

GET /api/v1/programs/<int:program_id>/analyze

›

Endpoint for retrieving the analysis data of a specific program.

Parameters

Name	Type	Description
program_id	int	ID of the program to analyze

Responses

Code

Description

200

Successfully retrieved analysis data

{
   "analysis": {
        "program": 1234,
        "user": 5678,
        "info": <analysis data>
    }
}

404

No analysis found for the program

{
   "error": "No analysis found"
}

POST /api/v1/programs/<int:program_id>/analyze

›

Endpoint for initiating the analysis of a specific program.

Parameters

Name	Type	Description
program_id	int	ID of the program to analyze.

Responses

Code

Description

200

Analysis is successfully initiated

{
   "message": "We are currently analyzing your program"
}

404

The specified program does not exist

{
   "error": "Program not found"
}

500

Internal server error when analysis is not finished

{
   "error": "Analyzed not finished"
}

POST /api/v1/programs/<int:program_id>/autoload

›

Endpoint for the Auto-mode "detect" pass: run Ghidra's native importer to detect the program's language and memory layout. The worker persists the detected language + sections via localapi; the user then reviews and edits them before running analysis.

Responses

Code	Description
200	Autoload is successfully initiated
404	The specified program does not exist
500	Internal server error

PUT /api/v1/programs/<int:program_id>/language

›

Endpoint for setting or overriding a program's language. Recovery path for when autoload didn't run / failed / can't detect the format, and a way to override a detected language.

Responses

Code	Description
200	Language updated
400	Invalid language
404	Program not found

POST /api/v1/programs/<int:program_id>/sections

›

Endpoint for creating sections within a specific program.

Parameters

Name	Type	Description
program_id	int	ID of the program to which sections are being added.

Responses

Code	Description
201	Successfully created sections { "sections": [<list of created section data>] }
400	Bad request for missing or invalid parameters { "error": "Invalid section data in section list" }
403	Forbidden if the program is currently under analysis { "error": "Cannot modify program while it is being analyzed" }
404	Program not found { "error": "Program not found" }

GET /api/v1/programs/<int:program_id>/sections

›

Endpoint for retrieving all sections associated with a specific program.

Parameters

Name	Type	Description
program_id	int	ID of the program whose sections are to be retrieved.

Responses

Code

Description

200

Successfully retrieved sections

{
   "sections": [<list of sections data>]
}

404

Program not found

{
   "error": "Program not found"
}

GET /api/v1/programs/<int:program_id>/sections/<int:section_id>

›

Endpoint for retrieving a specific section by its ID within a program.

Parameters

Name	Type	Description
program_id	int	ID of the program the section belongs to.
section_id	int	ID of the section to retrieve.

Responses

Code

Description

200

Successfully retrieved the section ```

```

404

Program or section not found

{
   "error": "Section not found"
}

DELETE /api/v1/programs/<int:program_id>/sections/<int:section_id>

›

Endpoint for deleting a specific section from a program.

Parameters

Name	Type	Description
program_id	int	ID of the program the section belongs to.
section_id	int	ID of the section to delete.

Responses

Code

Description

200

Successfully deleted the section

{
   "success": "Section deleted"
}

403

Forbidden if the program is currently under analysis

{
   "error": "Cannot modify program while it is being analyzed"
}

404

Program or section not found

{
   "error": "Section not found"
}

DELETE /api/v1/programs/<int:program_id>/sections/

›

Endpoint for deleting all sections associated with a specific program.

Parameters

Name	Type	Description
program_id	int	ID of the program whose sections are to be deleted.

Responses

Code

Description

200

Successfully deleted all sections

{
   "success": "All sections deleted"
}

403

Forbidden if the program is currently under analysis

{
   "error": "Cannot modify program while it is being analyzed"
}

404

Program not found

{
   "error": "Program not found"
}

POST /api/v1/programs/<int:program_id>/sections/<int:section_id>/functions

›

Endpoint for creating functions within a specific section of a program.

Parameters

Name	Type	Description
program_id	int	ID of the program containing the section.
section_id	int	ID of the section where functions are being added.

Responses

Code	Description
201	Successfully created functions { "functions": [<list of created function data>] }
400	Bad request for missing or invalid parameters { "error": "Invalid function data in list" }
403	Forbidden if the program is currently under analysis { "error": "Cannot modify program while it is being analyzed" }
404	Program or section not found { "error": "Program not found" }

GET /api/v1/programs/<int:program_id>/sections/<int:section_id>/functions

›

Endpoint for retrieving all functions within a specific section of a program.

Parameters

Name	Type	Description
program_id	int	ID of the program containing the section.
section_id	int	ID of the section whose functions are to be retrieved.

Responses

Code

Description

200

Successfully retrieved functions

{
   "functions": [<list of function data>]
}

404

Program or section not found

{
   "error": "Program not found"
}

GET /api/v1/programs/<int:program_id>/sections/<int:section_id>/functions/<int:function_id>

›

Endpoint for retrieving a specific function by its ID within a section of a program.

Parameters

Name	Type	Description
program_id	int	ID of the program containing the section.
section_id	int	ID of the section where the function resides.
function_id	int	ID of the function to retrieve.

Responses

Code

Description

200

Successfully retrieved the function

<function data>

404

Program, section, or function not found

{
   "error": "Function not found"
}

DELETE /api/v1/programs/<int:program_id>/sections/<int:section_id>/functions/<int:function_id>

›

Endpoint for deleting a specific function from a section of a program.

Parameters

Name	Type	Description
program_id	int	ID of the program containing the section.
section_id	int	ID of the section where the function resides.
function_id	int	ID of the function to delete.

Responses

Code

Description

200

Successfully deleted the function

{
   "success": "Function deleted"
}

403

Forbidden if the program is currently under analysis

{
   "error": "Cannot modify program while it is being analyzed"
}

404

Program, section, or function not found

{
   "error": "Function not found"
}

GET /api/v1/programs/<int:program_id>/sections/<int:section_id>/functions/<int:function_id>/matches

›

Endpoint for retrieving all matches related to a specific function within a section of a program.

Parameters

Name	Type	Description
program_id	int	ID of the program containing the section.
section_id	int	ID of the section where the function resides.
function_id	int	ID of the function whose matches are to be retrieved.

Responses

Code

Description

200

Successfully retrieved function matches

{
   "matches": [<list of match data>]
}

404

Program, section, or function not found

{
   "error": "Function not found"
}

Frontend API Reference

restapi

FrontendRestAPI

app

host

port

host property

port property

run

shutdown

admin_required

build_analysis_databases

get_current_user

Public REST API

Responses

Parameters

Responses

Responses

Responses

Responses

Responses

Responses

Responses

Responses

Responses

Parameters

Responses

Responses

Responses

Responses

Parameters

Responses

Responses

Parameters

Responses

Parameters

Responses

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Responses

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

`app`

`host`

`port`

host `property`

port `property`