Port Knocking Endpoints

Manage port knock sequences and access.

Pro Feature

Port Knocking endpoints require a Pro license.

List Sequences

Get all port knock sequences.

GET /api/v1/portknock/sequences

Response

Success (200):

{
  "sequences": [
    {
      "id": 1,
      "name": "ssh-access",
      "protected_port": 22,
      "knock_ports": [7000, 8000, 9000],
      "protocol": "tcp",
      "timeout": 30,
      "servers": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "hostname": "web-server-01"
        }
      ],
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 3
}

---

Get Sequence

Get a specific port knock sequence.

GET /api/v1/portknock/sequences/{sequenceId}

Path Parameters

Parameter	Type	Description
sequenceId	integer	Sequence ID

Response

Success (200):

{
  "id": 1,
  "name": "ssh-access",
  "protected_port": 22,
  "knock_ports": [7000, 8000, 9000],
  "protocol": "tcp",
  "timeout": 30,
  "knock_timeout": 5,
  "max_attempts": 3,
  "block_duration": 300,
  "servers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "hostname": "web-server-01"
    }
  ],
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-10T00:00:00Z"
}

---

Create Sequence

Create a new port knock sequence.

POST /api/v1/portknock/sequences

Request Body

{
  "name": "admin-panel",
  "protected_port": 8443,
  "knock_ports": [1111, 2222, 3333],
  "protocol": "tcp",
  "timeout": 60,
  "knock_timeout": 5,
  "max_attempts": 3,
  "block_duration": 300,
  "server_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}

Response

Success (201):

{
  "id": 4,
  "name": "admin-panel",
  "protected_port": 8443,
  "knock_ports": [1111, 2222, 3333],
  "created_at": "2024-01-15T10:30:00Z"
}

---

Update Sequence

Update an existing sequence.

PATCH /api/v1/portknock/sequences/{sequenceId}

Path Parameters

Parameter	Type	Description
sequenceId	integer	Sequence ID

Request Body

{
  "timeout": 45,
  "knock_ports": [1111, 2222, 3333, 4444]
}

Response

Success (200):

{
  "id": 4,
  "name": "admin-panel",
  "knock_ports": [1111, 2222, 3333, 4444],
  "timeout": 45,
  "updated_at": "2024-01-15T10:30:00Z"
}

---

Delete Sequence

Delete a port knock sequence.

DELETE /api/v1/portknock/sequences/{sequenceId}

Path Parameters

Parameter	Type	Description
sequenceId	integer	Sequence ID

Response

Success (200):

{
  "message": "Sequence deleted"
}

---

Perform Knock

Trigger a port knock from your current IP.

POST /api/v1/portknock/knock

Request Body

{
  "server_id": "550e8400-e29b-41d4-a716-446655440000",
  "sequence_name": "ssh-access"
}

Response

Success (200):

{
  "message": "Knock successful",
  "ip": "203.0.113.50",
  "protected_port": 22,
  "expires_at": "2024-01-15T10:31:00Z"
}

---

Get Active Openings

Get currently active port openings.

GET /api/v1/portknock/active

Query Parameters

Parameter	Type	Description
server_id	string	Filter by server UUID

Response

Success (200):

{
  "openings": [
    {
      "id": "open-abc123",
      "server": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "hostname": "web-server-01"
      },
      "sequence_name": "ssh-access",
      "ip": "203.0.113.50",
      "protected_port": 22,
      "opened_at": "2024-01-15T10:30:00Z",
      "expires_at": "2024-01-15T10:31:00Z"
    }
  ],
  "total": 3
}

---

Revoke Opening

Manually close an active port opening.

DELETE /api/v1/portknock/active/{openingId}

Path Parameters

Parameter	Type	Description
openingId	string	Opening ID

Response

Success (200):

{
  "message": "Opening revoked"
}

---

Get Knock History

Get port knock attempt history.

GET /api/v1/portknock/history

Query Parameters

Parameter	Type	Description
server_id	string	Filter by server UUID
sequence_id	integer	Filter by sequence
status	string	Filter by status: success, failed, blocked
from	string	Start date (ISO 8601)
to	string	End date (ISO 8601)
page	integer	Page number
limit	integer	Items per page

Response

Success (200):

{
  "history": [
    {
      "id": 12345,
      "server": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "hostname": "web-server-01"
      },
      "sequence_name": "ssh-access",
      "ip": "203.0.113.50",
      "status": "success",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "id": 12344,
      "server": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "hostname": "web-server-01"
      },
      "sequence_name": "ssh-access",
      "ip": "192.168.1.100",
      "status": "failed",
      "reason": "Wrong sequence",
      "timestamp": "2024-01-15T10:25:00Z"
    }
  ],
  "total": 500,
  "page": 1,
  "limit": 50
}

---

Get Blocked IPs

Get IPs currently blocked from knocking.

GET /api/v1/portknock/blocked

Response

Success (200):

{
  "blocked": [
    {
      "ip": "192.168.1.100",
      "server_id": "550e8400-e29b-41d4-a716-446655440000",
      "sequence_name": "ssh-access",
      "failed_attempts": 3,
      "blocked_at": "2024-01-15T10:25:00Z",
      "expires_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 2
}

---

Unblock IP

Manually unblock an IP.

DELETE /api/v1/portknock/blocked/{ip}

Path Parameters

Parameter	Type	Description
ip	string	IP address

Query Parameters

Parameter	Type	Description
server_id	string	Server UUID (optional, unblocks from all if not specified)

Response

Success (200):

{
  "message": "IP unblocked"
}

---

Get Statistics

Get port knocking statistics.

GET /api/v1/portknock/stats

Query Parameters

Parameter	Type	Description
period	string	day, week, month

Response

Success (200):

{
  "period": "day",
  "total_attempts": 150,
  "successful": 120,
  "failed": 25,
  "blocked": 5,
  "by_sequence": [
    { "name": "ssh-access", "attempts": 100, "success_rate": 85.0 },
    { "name": "admin-panel", "attempts": 50, "success_rate": 70.0 }
  ],
  "by_server": [
    { "hostname": "web-server-01", "attempts": 80 },
    { "hostname": "web-server-02", "attempts": 70 }
  ],
  "top_ips": [
    { "ip": "203.0.113.50", "attempts": 25 },
    { "ip": "203.0.113.51", "attempts": 20 }
  ]
}