Cisco Automated Software Distribution API

curl -s -X POST https://id.cisco.com/oauth2/default/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$CISCO_CLIENT_ID" \
  --data-urlencode "client_secret=$CISCO_CLIENT_SECRET"

# 200 OK
# {"access_token": "Er2cdpFDGNsQ...", "token_type": "Bearer", "expires_in": 3599}

POST https://apix.cisco.com/software/v4.0/metadata/pidrelease
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "pid": "C9300-48P",
  "currentReleaseVersion": "17.9.4",
  "outputReleaseVersion": "latest",
  "pageIndex": "1",
  "perPage": "25"
}

POST https://apix.cisco.com/software/v4.0/download/pidimage
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "pid": "ACS-1800-RM-19=",
  "mdfId": "286305578",
  "metadataTransId": "617462102359722937",
  "imageGuids": ["25856C5890AE73F8EDBEEDA441EC901F8FC8362E"]
}

# 200 OK (abridged from Cisco's sample)
{
  "sessionId": "205785277984030082",
  "downloads": [{
    "url": "https://…/download.cgi?dwnld_code=…",
    "token": "",
    "imageGuid": "25856C5890AE73F8EDBEEDA441EC901F8FC8362E",
    "imageName": "n9000-epld.7.0.3.I7.9.img",
    "exception": []
  }]
}

# Default URL (token field empty)
curl -fL -o "$IMAGE" "$URL&access_token=$ACCESS_TOKEN"

# Cloud URL (token field set): form POST, follow redirects
curl -fL -o "$IMAGE" -X POST "$URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "X-Authentication-Control=$CLOUD_TOKEN"

# Compare with the sha512 from the metadata call
echo "$SHA512  $IMAGE" | sha512sum -c -

# asd_client.py: Cisco Automated Software Distribution (ASD) API v4.0 client
# token cache, metadata lookup, EULA/K9 check, download URL, streamed download, SHA-512 check
import hashlib, os, sys, time, requests

TOKEN_URL = "https://id.cisco.com/oauth2/default/v1/token"
ASD = os.environ.get("ASD_BASE", "https://apix.cisco.com/software/v4.0")

class ASDClient:
    def __init__(self, client_id, client_secret, token_url=TOKEN_URL, base=ASD):
        self.cid, self.sec, self.token_url, self.base = client_id, client_secret, token_url, base
        self.s = requests.Session(); self.tok = None; self.exp = 0

    def token(self):
        if time.time() < self.exp:
            return self.tok
        r = self.s.post(self.token_url, data={"grant_type": "client_credentials",
                        "client_id": self.cid, "client_secret": self.sec}, timeout=30)
        r.raise_for_status(); j = r.json()
        self.tok = j["access_token"]
        self.exp = time.time() + int(j.get("expires_in", 3600)) - 300   # renew 5 min early
        return self.tok

    def post(self, path, body):
        for attempt in range(4):
            r = self.s.post(self.base + path, json=body, timeout=60,
                            headers={"Authorization": f"Bearer {self.token()}"})
            # The ASD error table reports rate and quota limits as 403, not 429
            if r.status_code in (403, 429, 502, 503, 504) and attempt < 3:
                if r.status_code == 403 and "Rate" not in r.text and "Over" not in r.text:
                    break                                  # a real permission error: stop
                time.sleep(2 ** attempt * 5); continue
            break
        if r.status_code >= 400:
            raise RuntimeError(f"{path} -> HTTP {r.status_code}: {r.text[:300]}")
        return r.json()

    @staticmethod
    def images(meta):
        """Flatten metadata -> products -> softwareTypes -> operatingSystems -> releases -> images."""
        for m in meta.get("metadata", []):
            for p in m.get("products", []):
                for st in p.get("softwareTypes", []):
                    for os_ in st.get("operatingSystems", []):
                        for rel in os_.get("releases", []):
                            for img in rel.get("images", []):
                                yield {"pid": m.get("pid"), "mdfId": p.get("mdfId"),
                                       "release": rel.get("version") or rel.get("releaseVersion"),
                                       "suggested": rel.get("isSuggested"),
                                       "name": img.get("name") or img.get("imageName"),
                                       "guid": img.get("imageGuid"),
                                       "size": img.get("size") or img.get("imageSize"),
                                       "sha512": img.get("sha512"), "md5": img.get("md5"),
                                       "exceptions": [e.get("code") for e in img.get("exception", [])]}

    def metadata_by_release(self, pid, current, output="latest", page=1):
        # Field casing follows Cisco's sample request; the parameter table spells some differently
        return self.post("/metadata/pidrelease", {"pid": pid, "currentReleaseVersion": current,
                         "outputReleaseVersion": output, "pageIndex": str(page), "perPage": "25"})

    def metadata_by_image(self, pid, image_names):
        return self.post("/metadata/pidimage", {"pid": pid, "imageNames": image_names[:5],
                         "pageIndex": "1", "perPage": "25"})

    def accept(self, kind, file_name):
        # kind is "eula" or "k9"; only call after reviewing the agreement with the right owner
        body = {"status": "Accepted", "fileNames": file_name}
        if kind == "k9":
            body.update({"busFunction": "COMM_OR_CIVIL", "confirm": "CONFIRM_CHECKED"})
        return self.post(f"/compliance/{kind}", body)

    def download_urls(self, pid, mdf_id, guids, trans_id):
        return self.post("/download/pidimage", {"pid": pid, "mdfId": str(mdf_id),
                         "imageGuids": guids[:5], "metadataTransId": trans_id})

    def fetch(self, item, dest):
        """Stream one entry of downloads[] to disk; returns the SHA-512 of the bytes written."""
        h = hashlib.sha512()
        if item.get("token"):    # image is in Cisco's cloud store: form-encoded POST, follow 302s
            r = self.s.post(item["url"], data={"X-Authentication-Control": item["token"]},
                            stream=True, allow_redirects=True, timeout=600)
        else:                    # default download URL: append the API access token
            r = self.s.get(item["url"] + "&access_token=" + self.token(),
                           stream=True, allow_redirects=True, timeout=600)
        r.raise_for_status()
        with open(dest, "wb") as f:
            for chunk in r.iter_content(1 << 20):
                f.write(chunk); h.update(chunk)
        return h.hexdigest()

if __name__ == "__main__":
    pid, current = sys.argv[1], sys.argv[2]
    c = ASDClient(os.environ["CISCO_CLIENT_ID"], os.environ["CISCO_CLIENT_SECRET"])
    meta = c.metadata_by_release(pid, current, "latest")
    trans = meta["metadataTransId"]                       # valid for 60 minutes
    imgs = list(c.images(meta))
    for i in imgs:
        print(f'{i["release"]:<14} {i["name"]:<48} {i["size"]:>12}  {",".join(i["exceptions"]) or "ok"}')
    ok = [i for i in imgs if not i["exceptions"]]
    if not ok:
        sys.exit("No downloadable image: resolve the exception codes above first")
    pick = ok[0]
    d = c.download_urls(pid, pick["mdfId"], [pick["guid"]], trans)
    item = d["downloads"][0]
    if item.get("exception"):
        sys.exit(f'Download blocked: {[e.get("code") for e in item["exception"]]}')
    got = c.fetch(item, item["imageName"])
    if pick["sha512"] and got.lower() != pick["sha512"].lower():
        os.remove(item["imageName"]); sys.exit("SHA-512 mismatch: file deleted")
    print(f'{item["imageName"]} downloaded and SHA-512 verified')

pip install requests
export CISCO_CLIENT_ID=…  CISCO_CLIENT_SECRET=…
python asd_client.py C9300-48P 17.9.4
# 17.12.6        cat9k_iosxe.17.12.06.SPA.bin   …  ok
# cat9k_iosxe.17.12.06.SPA.bin downloaded and SHA-512 verified

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://apix.cisco.com/software/suggestion/v2/suggestions/releases/productIds/C9300-48P,C9500-48Y4C?pageIndex=1"

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://apix.cisco.com/product/v1/information/product_ids_mdf/ASA5505-50-BUN-K9?page_index=1"
# product_list[0].product_name_mdf   -> MDF ID of the product
# product_list[0].product_series_mdf -> MDF ID of the series