Skip to content

Frontend API Reference

restapi

Public REST API for SightHouse clients

Classes:

Functions:

FrontendRestAPI 

FrontendRestAPI(database: FrontendDatabase, celery_url: str, ghidra_dir: Path, bsims: Optional[List[str]], fidbs: Optional[List[str]], logger: Logger, host: str = '0.0.0.0', port: int = 6671)

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:

  • is_program_under_analysis –

    Return whether the given program is under analysis or not

  • run –

    Starts the HTTP server, listening for incoming requests

  • shutdown –

    Shuts down the running server gracefully.

Source code in venv/lib/python3.12/site-packages/sighthouse/frontend/restapi.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
def __init__(
    self,
    database: FrontendDatabase,
    celery_url: str,
    ghidra_dir: Path,
    bsims: Optional[List[str]],
    fidbs: Optional[List[str]],
    logger: Logger,
    host: str = "0.0.0.0",
    port: int = 6671,
):
    self.__database: FrontendDatabase = database
    self.__logger = logger
    self.__app = Flask(__name__)
    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.__ghidra_dir = ghidra_dir
    self.__fidbs = fidbs or []
    self.__bsims = bsims or []
    self.__celery_app = Celery("", broker=celery_url, backend=celery_url)  # Useless

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

is_program_under_analysis 

is_program_under_analysis(program_id: int) -> bool

Return whether the given program is under analysis or not

Parameters:

  • program_id
    (int) –

    The ID of the program

Returns:

  • bool ( bool ) –

    True if the program is currently being analyzed, False otherwise

Source code in venv/lib/python3.12/site-packages/sighthouse/frontend/restapi.py 
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
def is_program_under_analysis(self, program_id: int) -> bool:
    """Return whether the given program is under analysis or not

    Args:
        program_id (int): The ID of the program

    Returns:
        bool: True if the program is currently being analyzed, False otherwise
    """
    analysis = self.__database.get_analysis(program_id)
    if not analysis or analysis.info.get("status") == "finished":
        return False

    return True

run 

run() -> None

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

Source code in venv/lib/python3.12/site-packages/sighthouse/core/utils/api.py 
37
38
39
40
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 venv/lib/python3.12/site-packages/sighthouse/core/utils/api.py 
42
43
44
def shutdown(self) -> None:
    """Shuts down the running server gracefully."""
    self.__server.shutdown()

get_current_user 

get_current_user() -> User

Wrapper function so mypy stop yelling at me

Source code in venv/lib/python3.12/site-packages/sighthouse/frontend/restapi.py 
46
47
48
49
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/ping
›

Health check endpoint

Responses

CodeDescription
200

successful operation 

{
     "success": "Pong !"
 }

POST /api/v1/login
›

Login endpoint

Parameters

NameTypeDescription
userstr

The username for the login

passwordstr

The password for the login

Responses

CodeDescription
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

CodeDescription
200

Successful operation 

{
   "success": "Login successful"
}

GET /api/v1/languages
›

List languages supported by the analyzer

Responses

CodeDescription
200

Successful operation 

{
   "languages": ["ARM", ...]
}

POST /api/v1/uploads
›

Endpoint for upload files into the server

Parameters

NameTypeDescription
filenamestr, bytes

Multipart encoded file to upload

Responses

CodeDescription
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

CodeDescription
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

NameTypeDescription
hashstr

hash of the file to delete

Responses

CodeDescription
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

NameTypeDescription
programslist[program]

A list of JSON program to create

Responses

CodeDescription
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

CodeDescription
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

NameTypeDescription
program_idint

ID of the requested program

recursivestr

A string corresponding to a boolean (either 'true' or 'false') that tell the server to return the program sub elements such as functions.

Responses

CodeDescription
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

NameTypeDescription
program_idint

ID of the program to delete

Responses

CodeDescription
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

NameTypeDescription
program_idint

ID of the program to analyze

Responses

CodeDescription
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

NameTypeDescription
program_idint

ID of the program to analyze.

Responses

CodeDescription
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>/sections
›

Endpoint for creating sections within a specific program.

Parameters

NameTypeDescription
program_idint

ID of the program to which sections are being added.

Responses

CodeDescription
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

NameTypeDescription
program_idint

ID of the program whose sections are to be retrieved.

Responses

CodeDescription
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

NameTypeDescription
program_idint

ID of the program the section belongs to.

section_idint

ID of the section to retrieve.

Responses

CodeDescription
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

NameTypeDescription
program_idint

ID of the program the section belongs to.

section_idint

ID of the section to delete.

Responses

CodeDescription
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

NameTypeDescription
program_idint

ID of the program whose sections are to be deleted.

Responses

CodeDescription
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

NameTypeDescription
program_idint

ID of the program containing the section.

section_idint

ID of the section where functions are being added.

Responses

CodeDescription
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

NameTypeDescription
program_idint

ID of the program containing the section.

section_idint

ID of the section whose functions are to be retrieved.

Responses

CodeDescription
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

NameTypeDescription
program_idint

ID of the program containing the section.

section_idint

ID of the section where the function resides.

function_idint

ID of the function to retrieve.

Responses

CodeDescription
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

NameTypeDescription
program_idint

ID of the program containing the section.

section_idint

ID of the section where the function resides.

function_idint

ID of the function to delete.

Responses

CodeDescription
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

NameTypeDescription
program_idint

ID of the program containing the section.

section_idint

ID of the section where the function resides.

function_idint

ID of the function whose matches are to be retrieved.

Responses

CodeDescription
200

Successfully retrieved function matches 

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

404

Program, section, or function not found 

{
   "error": "Function not found"
}