SUBTASK #49: Scan and device API endpoints

Open
  • Is something wrong?
#51 0 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@PavlockBlaine03 is already working on this.

Since Oct 27, 2026.

Assessment

This issue has not been assessed yet.

Description

backend High Priority subtask

What to do

The three endpoints the screens need: start a scan, get the scan status, and list devices. Each route checks access (the placeholder from #50), calls one service, and returns JSON in the shapes below. The shapes in this ticket are the contract: the scan screen and device list (subtasks 3 and 4) are built against them, so changing them later means changing those screens too.

Background

  • Spec: WF-01, FR-13, OUT-01 (device inventory), OUT-03 (flag), OUT-06 (scan status and errors), CM-09, CM-11, CM-15
  • System design: 2.0 routes requests; 2.2 Scan Manager (start), 2.2.1.3 Report Scan Status, 3.1.2 Find Devices; section 14.1 (paginated results)
  • Rules are in #49.

The endpoints and their JSON

POST /api/scans: start a scan

Request: {"scope": "192.168.1.0/24"}

Result Status Body
Started 202 Accepted {"scan_id": 12, "status_url": "/api/scans/status"}
Another scan is running 409 Conflict {"error": "A scan started by sam at 14:03 is still running."}
Bad or missing scope 400 Bad Request {"error": "10.0.0.0/8 is larger than the limit of 1024 addresses"}

The scan is started as the user making the request (the #50 placeholder until M4), so it records who started it (CM-11).

GET /api/scans/status: what the scanner is doing

While a scan runs:

{"running": true, "scan_id": 12, "scope": "192.168.1.0/24",
 "started_by": "sam", "started_at": "2026-10-26T14:03:00", "elapsed_seconds": 6,
 "phase": "discovering_hosts", "done": 120, "total": 254,
 "errors": ["ping unavailable: ping command not found"]}

When nothing is running:

{"running": false, "last_scan": {"scan_id": 12, "scope": "192.168.1.0/24",
 "started_by": "sam", "started_at": "2026-10-26T14:03:00", "ended_at": "2026-10-26T14:03:11",
 "outcome": "partial", "errors": ["ping unavailable: ping command not found"]}}

Before any scan: {"running": false, "last_scan": null}

GET /api/devices?page=1&per_page=50: the device list
{"devices": [
   {"device_id": 7, "name": null, "type": "unknown", "vendor": "Apple, Inc.",
    "ip": "192.168.1.23", "mac": "F0:D1:A9:12:34:56", "is_randomized_mac": false,
    "network_status": "online", "confidence": 20, "flagged": true, "trusted": false,
    "last_seen": "2026-10-26T14:03:09"}],
 "page": 1, "per_page": 50, "total": 14}
  • Vendor and type are names, not ids. Name is null when unknown; the screen shows "Unknown".
  • Sorted by last_seen, newest first. per_page defaults to 50, maximum 200.
  • Bad page / per_page (not a number, 0, over 200): 400 with a reason.

Steps

  • backend/controller/api_routes.py, registered through #50's register_routes
  • Each route: the access check (#50), one service call, the JSON above. No database code in the routes (tier rules).
  • The device list needs vendor and type names in one query, not one lookup per device. If 3.1.2 Find Devices (#15) only returns ids, add a list query to 3.1 that joins the vendor and device_type names and supports LIMIT / OFFSET plus a total count.
  • Don't use find_reference_rules() for the names: it leaves out retired vendors and types, but devices still show them (DI-06).
  • Write the three JSON examples above into the README's API section, so the screen builders have them.
  • Tests with Flask's test client and fake services (no database or network):
    • Start: 202 with the scan id; 409 with the refusal text; 400 for a bad scope and for a missing body
    • Start passes the calling user's id to the Scan Manager
    • Status: the running shape, the finished shape, and the "no scans yet" shape
    • Devices: names instead of ids, newest first, paging (total correct, second page right), empty list, bad paging values

Where

backend/controller/api_routes.py, possibly a list query in backend/data_access/network_data/, tests/controller/test_api_routes.py

Done when

  • With the app running, POST /api/scans starts a real scan, GET /api/scans/status follows it to the end, and GET /api/devices then lists the devices found
  • All route tests pass without a database

Depends on

  • #50 Application entry point and controller
  • #48 Scan Manager (start) and #47 Report Scan Status
  • #15 Network Data (3.1.2 Find Devices)
Dominant language
Python
Stars
1
Forks
1
Avg merge
9h 31m
Merged PRs (30d)
36

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Bearkat-Professionals/Software-Engineering-Project

All issues in Bearkat-Professionals/Software-Engineering-Project

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.