carcal 0.2.0__py3-none-win_amd64.whl

carcal/__init__.py

@@ -0,0 +1 @@
+"""carcal — a terminal packet analyzer. See `carcal --help`."""

carcal/__main__.py

@@ -0,0 +1,41 @@
+"""Entry point for the `carcal` console script."""
+import os
+import sys
+from pathlib import Path
+
+_BUNDLE = Path(__file__).resolve().parent / "_bundle"
+
+
+def _layout():
+    """(executable, protos, grammars) — the Windows bundle is flat, the others
+    are bin/ + lib/ + share/."""
+    win = _BUNDLE / "carcal.exe"
+    if win.exists():
+        return win, _BUNDLE / "protos", _BUNDLE / "grammars"
+    share = _BUNDLE / "share" / "carcal"
+    return _BUNDLE / "bin" / "carcal", share / "protos", share / "grammars"
+
+
+def main() -> int:
+    exe, protos, grammars = _layout()
+    if not exe.exists():
+        sys.exit(f"carcal: bundled binary is missing from {_BUNDLE} "
+                 f"(broken install — try reinstalling)")
+
+    env = dict(os.environ)
+    # setdefault, not assignment: an explicit CARCAL_PROTOS_DIR is how a user
+    # points carcal at their own .posa decoders, and it must still win.
+    env.setdefault("CARCAL_PROTOS_DIR", str(protos))
+    env.setdefault("CARCAL_GRAMMARS_DIR", str(grammars))
+
+    argv = [str(exe), *sys.argv[1:]]
+    if os.name == "nt":
+        # execve on Windows returns control to the shell immediately, which
+        # would hand a live TUI a prompt it is fighting for; spawn and wait.
+        import subprocess
+        return subprocess.run(argv, env=env).returncode
+    os.execve(exe, argv, env)   # no return
+
+
+if __name__ == "__main__":
+    sys.exit(main())

carcal/_bundle/grammars/posa.tmLanguage.json

@@ -0,0 +1,20 @@
+{
+  "name": "posa",
+  "scopeName": "source.posa",
+  "fileTypes": ["posa"],
+  "patterns": [
+    { "name": "comment.line.number-sign.posa", "match": "#.*$" },
+    { "name": "keyword.other.binding.posa", "match": "^\\s*(rule|color)\\b" },
+    { "name": "keyword.control.posa",
+      "match": "\\b(Object|protocol|end|default|required|optional|when|else|scope|repeat|until|as|label|bits|seek|layer|include|info|col|abbrev|mask|hex)\\b" },
+    { "name": "storage.type.posa",
+      "match": "\\b(uint8|uint16|uint24|uint32|uint64|le_uint16|le_uint32|le_uint64|mac|ip4|ip6|cstring|string|payload|dnsname)\\b" },
+    { "name": "storage.type.posa", "match": "\\b(bytes|str|utf16)(?=[<\\[])" },
+    { "name": "entity.name.type.parent.posa", "match": "<[A-Za-z0-9_]+>" },
+    { "name": "string.quoted.double.posa", "match": "\"(\\\\.|[^\"\\\\])*\"" },
+    { "name": "keyword.operator.posa", "match": "(==|!=|<=|>=|=>|<|>|=|&)" },
+    { "name": "constant.numeric.hex.posa", "match": "\\b0[xX][0-9a-fA-F]+\\b" },
+    { "name": "constant.numeric.posa", "match": "\\b[0-9]+\\b" },
+    { "name": "variable.other.field.posa", "match": "\\b[a-z_][a-z0-9_]*\\b" }
+  ]
+}

carcal/_bundle/protos/dhcp.posa

@@ -0,0 +1,114 @@
+# dhcp.posa — DHCP / BOOTP (RFC 2131, 2132).
+#
+# A fixed BOOTP header, then a magic cookie, then options: a stream of
+# type-length-value records with no count in front of them. That is
+#
+#   repeat until end as option    records until the packet runs out
+#       scope opt_len             each option's value is opt_len bytes, and the
+#                                 scope ends there whether we decoded it or not —
+#                                 so an option this file has never heard of still
+#                                 leaves the walk on the right byte
+#       when opt_code == 53:      the ones worth naming get named…
+#       else:                     …and the rest still show their bytes
+#
+# Pad (0) and End (255) carry no length byte, hence the `when opt_code > 0` /
+# `when opt_code < 255` nesting around the length.
+
+Object<main> DHCP
+    abbrev "dhcp"
+    col "DHCP"
+
+    required uint8 op "Message Type"
+        Boot Request = 1
+        Boot Reply = 2
+    required uint8 htype "Hardware Type"
+        Ethernet = 1
+    required uint8 hlen "Hardware Address Length"
+    required uint8 hops "Hops"
+    required uint32 xid hex "Transaction ID"
+    required uint16 secs "Seconds Elapsed"
+    required uint16 flags hex "Flags"
+        bits flags broadcast 15 1 "Broadcast"
+    required ip4 ciaddr "Client IP Address"
+    required ip4 yiaddr "Your (client) IP Address"
+    required ip4 siaddr "Next Server IP Address"
+    required ip4 giaddr "Relay Agent IP Address"
+    required mac chaddr "Client MAC Address"
+    required bytes<10> chaddr_pad "Client Hardware Address Padding"
+    required bytes<64> sname "Server Host Name"
+    required bytes<128> file "Boot File Name"
+    required uint32 cookie hex "Magic Cookie"
+
+    repeat until end as option "Options"
+        label "%s: %s%s%s" opt_code, msg_type, opt_ip, opt_text
+        required uint8 opt_code "Option"
+            Pad = 0
+            Subnet Mask = 1
+            Router = 3
+            Domain Name Server = 6
+            Host Name = 12
+            Domain Name = 15
+            Requested IP Address = 50
+            IP Address Lease Time = 51
+            DHCP Message Type = 53
+            Server Identifier = 54
+            Parameter Request List = 55
+            Maximum DHCP Message Size = 57
+            Renewal Time Value = 58
+            Rebinding Time Value = 59
+            Vendor Class Identifier = 60
+            Client Identifier = 61
+            End = 255
+        when opt_code > 0:
+            when opt_code < 255:
+                required uint8 opt_len "Length"
+                scope opt_len
+                    when opt_code == 53:
+                        required uint8 msg_type "DHCP Message Type"
+                            Discover = 1
+                            Offer = 2
+                            Request = 3
+                            Decline = 4
+                            ACK = 5
+                            NAK = 6
+                            Release = 7
+                            Inform = 8
+                    when opt_code == 1:
+                        required ip4 opt_ip "Subnet Mask"
+                    when opt_code == 3:
+                        required ip4 opt_ip "Router"
+                    when opt_code == 6:
+                        repeat until end as dns_server
+                            label "DNS Server: %s" opt_ip
+                            required ip4 opt_ip "Domain Name Server"
+                    when opt_code == 50:
+                        required ip4 opt_ip "Requested IP Address"
+                    when opt_code == 54:
+                        required ip4 opt_ip "Server Identifier"
+                    when opt_code == 51:
+                        required uint32 lease_time "IP Address Lease Time"
+                    when opt_code == 12:
+                        required str[opt_len] opt_text "Host Name"
+                    when opt_code == 15:
+                        required str[opt_len] opt_text "Domain Name"
+                    when opt_code == 60:
+                        required str[opt_len] opt_text "Vendor Class Identifier"
+                    when opt_code == 55:
+                        repeat until end as requested
+                            label "Requested: %s" param
+                            required uint8 param "Parameter"
+                                Subnet Mask = 1
+                                Router = 3
+                                Domain Name Server = 6
+                                Host Name = 12
+                                Domain Name = 15
+                                Broadcast Address = 28
+                    else:
+                        required payload opt_value "Value"
+
+    info "DHCP %s - Transaction ID 0x%x" msg_type, xid
+
+rule udp.port == 67 => DHCP
+rule udp.port == 68 => DHCP
+
+color dhcp => black lightblue

carcal/_bundle/protos/dns.posa

@@ -0,0 +1,176 @@
+# dns.posa — DNS / mDNS / LLMNR (RFC 1035, RFC 6762), the whole message.
+#
+# This is the decoder carcal uses for ports 53, 5353 and 5355 — there is no C
+# dissector behind it. Read it as the spec: a header, then four sections of
+# records, each section repeated as many times as its counter says.
+#
+# The pieces of posa that make a record protocol expressible:
+#
+#   repeat <count> as <item>   one subtree per record, count taken from a field
+#   repeat until end as <item> records until the enclosing scope runs out
+#   label "..." a, b           how to title a record's subtree, from its fields
+#   dnsname                    a name, following 0xc0 compression pointers
+#   bits <src> <n> <sh> <w>    a bitfield carved out of an already-parsed field
+#   scope <lenfield>           bound the next fields to <lenfield> bytes (rdata)
+#   include <Object>           inline another object's fields (the RR body,
+#                              shared by the answer/authority/additional sections)
+#
+# To change what you see: edit this file (Analyze ▸ Decoders ▸ DNS ▸ Enter) and
+# save — no rebuild. Add an RR type by adding a `when type == N:` block.
+
+# ── A resource record ────────────────────────────────────────────────────────
+# Name, type, class, TTL, then rdlength bytes of type-dependent data. `scope
+# rdlength` bounds the rdata so an unknown type still leaves the walk on the
+# right byte — the scope ends where rdlength says, decoded or not.
+#
+# Defined first because the three record sections below `include` it.
+Object<main> RR
+    abbrev "dns"
+
+    required dnsname name "Name"
+    required uint16 type "Type"
+        A = 1
+        NS = 2
+        CNAME = 5
+        SOA = 6
+        PTR = 12
+        HINFO = 13
+        MX = 15
+        TXT = 16
+        AAAA = 28
+        SRV = 33
+        OPT = 41
+        NSEC = 47
+        HTTPS = 65
+    required uint16 class mask 0x7fff "Class"
+        IN = 1
+        CH = 3
+        ANY = 255
+    # mDNS reuses the top class bit to mean "flush your cache for this name"
+    bits class flush 15 1 "Cache flush"
+    required uint32 ttl "Time to live"
+    required uint16 rdlength "Data length"
+
+    scope rdlength
+        when type == 1:
+            required ip4 rdata "Address"
+        when type == 28:
+            required ip6 rdata "Address"
+        when type == 12:
+            required dnsname rdata "Domain name"
+        when type == 5:
+            required dnsname rdata "CNAME"
+        when type == 2:
+            required dnsname rdata "Name server"
+        when type == 15:
+            required uint16 preference "Preference"
+            required dnsname rdata "Mail exchange"
+        when type == 33:
+            required uint16 priority "Priority"
+            required uint16 weight "Weight"
+            required uint16 port "Port"
+            required dnsname rdata "Target"
+        when type == 6:
+            required dnsname rdata "Primary name server"
+            required dnsname rname "Responsible mailbox"
+            required uint32 serial "Serial"
+            required uint32 refresh "Refresh"
+            required uint32 retry "Retry"
+            required uint32 expire "Expire"
+            required uint32 minimum "Minimum TTL"
+        # TXT is a run of length-prefixed strings — "model=J96AP", "osxvers=21", …
+        # There is no count for them, so repeat until the rdata scope runs out.
+        when type == 16:
+            repeat until end as txt
+                label "%s" rdata
+                required uint8 txtlen "Length"
+                required str[txtlen] rdata "Text"
+        when type == 41:
+            required payload rdata "Options"
+        when type == 47:
+            required dnsname rdata "Next domain name"
+
+Object<main> DNS
+    abbrev "dns"
+    col "DNS"
+
+    required uint16 id "Transaction ID"
+    required uint16 flags "Flags"
+        bits flags qr     15 1 "Response"
+            Query = 0
+            Response = 1
+        bits flags opcode 11 4 "Opcode"
+            QUERY = 0
+            IQUERY = 1
+            STATUS = 2
+            NOTIFY = 4
+            UPDATE = 5
+        bits flags aa     10 1 "Authoritative"
+        bits flags tc      9 1 "Truncated"
+        bits flags rd      8 1 "Recursion desired"
+        bits flags ra      7 1 "Recursion available"
+        bits flags rcode   0 4 "Reply code"
+            NoError = 0
+            FormErr = 1
+            ServFail = 2
+            NXDomain = 3
+            NotImp = 4
+            Refused = 5
+    required uint16 questions "Questions"
+    required uint16 answers "Answer RRs"
+    required uint16 authority "Authority RRs"
+    required uint16 additional "Additional RRs"
+
+    # ── Queries ───────────────────────────────────────────────────────────────
+    # A question is a name, a type, and a class. In mDNS the top class bit is the
+    # "QU" bit (send the reply unicast), so the class is masked and the bit shown
+    # on its own — that is what `mask` and `bits` are for.
+    repeat questions as query "Queries"
+        label "%s: type %s, class %s" qname, qtype, qclass
+        required dnsname qname "Name"
+        required uint16 qtype "Type"
+            A = 1
+            NS = 2
+            CNAME = 5
+            SOA = 6
+            PTR = 12
+            HINFO = 13
+            MX = 15
+            TXT = 16
+            AAAA = 28
+            SRV = 33
+            OPT = 41
+            NSEC = 47
+            HTTPS = 65
+            ANY = 255
+        required uint16 qclass mask 0x7fff "Class"
+            IN = 1
+            CH = 3
+            NONE = 254
+            ANY = 255
+        bits qclass qu 15 1 "QU (reply wanted unicast)"
+            Multicast = 0
+            Unicast = 1
+
+    repeat answers as answer "Answers"
+        label "%s: type %s, class %s, %s" name, type, class, rdata
+        include RR
+
+    repeat authority as authority_rr "Authoritative nameservers"
+        label "%s: type %s, class %s, %s" name, type, class, rdata
+        include RR
+
+    repeat additional as additional_rr "Additional records"
+        label "%s: type %s, class %s, %s" name, type, class, rdata
+        include RR
+
+    # A query has questions and no records; a response is usually the reverse —
+    # name both, and the fields the packet does not carry expand to nothing.
+    info "%s 0x%x %s %s %s %s" qr, id, qtype, qname, type, rdata
+
+rule udp.port == 53   => DNS
+rule udp.port == 5353 => DNS
+rule udp.port == 5355 => DNS
+
+color dns.rcode > 0 => yellow red
+color dns           => white blue

carcal/_bundle/protos/http.posa

@@ -0,0 +1,59 @@
+# http.posa — HTTP/1.x (RFC 9112).
+#
+# HTTP has no lengths in front of anything: it is lines of text ending in CRLF,
+# then a blank line, then the body. Two posa constructs cover that shape:
+#
+#   string <name> until "<delim>"      one delimited token
+#   repeat until "<delim>" as <item>   records until those bytes come next —
+#                                      here, header lines until the blank line
+#
+# A request and a response differ only in their first line, so they are two
+# objects in an Object<HTTP> group, told apart by their first field: a response
+# starts with "HTTP", a request with a method. The group is dispatched on the
+# first field's value, so "HTTP" as a uint32 (0x48545450) selects the response.
+#
+# Not covered (add it here, no rebuild): chunked transfer-encoding is shown as
+# the raw body, and the body is not decompressed.
+
+Object<HTTP> HTTP_RESPONSE
+    abbrev "http"
+    col "HTTP"
+
+    # the group is dispatched on the first field's value, so a response is
+    # recognised by its "HTTP" magic — then `seek 0` rewinds over it, and the
+    # status line is read as the text it actually is
+    required uint32 magic = 0x48545450 hex "Magic"
+    seek 0
+    required string version until " " "Version"
+    required string status_code until " " "Status Code"
+    required string reason until "\r\n" "Reason Phrase"
+    repeat until "\r\n" as header "Headers"
+        label "%s" line
+        required string line until "\r\n" "Header"
+    required string blank until "\r\n" "End of headers"
+    required payload body "Body"
+
+    info "%s %s" status_code, reason
+
+Object<HTTP> HTTP_REQUEST default
+    abbrev "http"
+    col "HTTP"
+
+    required string method until " " "Method"
+    required string uri until " " "Request URI"
+    required string version until "\r\n" "Version"
+    repeat until "\r\n" as header "Headers"
+        label "%s" line
+        required string line until "\r\n" "Header"
+    required string blank until "\r\n" "End of headers"
+    required payload body "Body"
+
+    info "%s %s %s" method, uri, version
+
+rule tcp.port == 80   => HTTP
+rule tcp.port == 8080 => HTTP
+rule tcp.port == 8000 => HTTP
+rule tcp.port == 8888 => HTTP
+rule tcp.port == 3128 => HTTP
+
+color http => black lightgray

carcal/_bundle/protos/igmp.posa

@@ -0,0 +1,56 @@
+# igmp.posa — IGMP v1/v2/v3 (RFC 1112, 2236, 3376).
+#
+# Bound by IP protocol number, not a port:  rule ip.proto == 2 => IGMP
+#
+# The v3 membership report (type 0x22) is a different shape from the queries and
+# the v1/v2 reports: no group address in the header, just a count of the group
+# records that follow, each with its own list of source addresses. That is two
+# nested `repeat`s — the outer one counted by a header field, the inner by a
+# field of the record it is inside.
+#
+# Every field a posa decoder produces carries its byte range, so selecting a row
+# in the details pane highlights the right bytes in the hex pane. That is free
+# here; in hand-written C it is a call you can forget to make.
+
+Object<main> IGMP
+    abbrev "igmp"
+    col "IGMP"
+
+    required uint8 type "Type"
+        Membership Query = 0x11
+        IGMPv1 Membership Report = 0x12
+        IGMPv2 Membership Report = 0x16
+        Leave Group = 0x17
+        IGMPv3 Membership Report = 0x22
+    required uint8 max_resp "Max Resp Time"
+    required uint16 checksum "Checksum"
+
+    # v3 membership report: reserved, then N group records
+    when type == 0x22:
+        required uint16 reserved "Reserved"
+        required uint16 num_records "Num Group Records"
+        repeat num_records as record "Group Records"
+            label "%s: %s (%u source(s))" record_type, maddr, num_sources
+            required uint8 record_type "Record Type"
+                MODE_IS_INCLUDE = 1
+                MODE_IS_EXCLUDE = 2
+                CHANGE_TO_INCLUDE = 3
+                CHANGE_TO_EXCLUDE = 4
+                ALLOW_NEW_SOURCES = 5
+                BLOCK_OLD_SOURCES = 6
+            required uint8 aux_len "Aux Data Length"
+            required uint16 num_sources "Num Sources"
+            required ip4 maddr "Multicast Address"
+            repeat num_sources as source "Source Addresses"
+                label "Source: %s" saddr
+                required ip4 saddr "Source Address"
+
+    # everything else (queries, v1/v2 reports, leave) carries a group address
+    when type != 0x22:
+        required ip4 maddr "Multicast Address"
+
+    info "%s %s" type, maddr
+
+rule ip.proto == 2 => IGMP
+
+color igmp => black lightgreen

carcal/_bundle/protos/rdp.posa

@@ -0,0 +1,57 @@
+# rdp.posa — Remote Desktop Protocol over TPKT / ISO-8073 (COTP), fully in posa.
+# Demonstrates the extended grammar: layered sub-protocols, length scopes,
+# conditional layout, a delimiter field, a derived Info string, and a port rule.
+
+protocol TPKT
+    col "RDP"
+    abbrev "rdp"
+    required uint8  version
+    required uint8  reserved
+    required uint16 length
+    layer   cotp    COTP
+
+protocol COTP
+    abbrev "cotp"
+    required uint8  li
+    required uint8  pdu_type
+        CR = 0xe0
+        CC = 0xd0
+        DT = 0xf0
+    scope   li
+        when pdu_type & 0xf0 == 0xe0:
+            required uint16 dst_ref
+            required uint16 src_ref
+            required uint8  class
+            layer neg RDP_NEGOTIATION
+        when pdu_type & 0xf0 == 0xd0:
+            required uint16 dst_ref
+            required uint16 src_ref
+            required uint8  class
+            layer neg RDP_NEGOTIATION
+        when pdu_type & 0xf0 == 0xf0:
+            required uint8  eot
+    info "COTP %s" pdu_type
+
+protocol RDP_NEGOTIATION
+    abbrev "rdp"
+    optional string cookie until "\r\n"
+    when remaining >= 8:
+        required uint8 type
+            Request  = 1
+            Response = 2
+            Failure  = 3
+        required uint8     flags
+        required le_uint16 length
+        required le_uint32 protocols
+            TLS     = 0x1
+            CredSSP = 0x3
+    info "%s Negotiate %s" cookie, type
+
+rule tcp.port == 3389 => TPKT
+
+# Coloring — carcal paints a matching packet with these colors, first match wins.
+# Declared here so the decoder ships its own look: drop this file into protos/
+# and RDP is both decoded and colored, with no rebuild. Consulted before
+# carcal's generic tcp rule, so they win over it.
+color rdp.type == 3 => yellow red      # negotiation Failure
+color rdp           => black lightcyan