Really poor documentation....?

Open
#94 3 comments 7 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
28/100
Issue type
Documentation
Clarity
Needs clarification
Activity status
Stale
Tech stack
azure, typescript
Domain
devops, documentation

Research direction

Start by reviewing the wiki and the MicrosoftSecurityDevOps@1 task configuration shown in the issue, including environment variables, categories, tools, and command inputs. Document when to use categories versus tools, how to configure variables such as Terrascan_IacDir, and provide a validated working example covering the reported failure and successful configuration.

Written by the indexing model from the issue text.

Description

Almost nothing else to say, it's quite clear to anyone that hits this product and it's repo.

Let me explain why it is very disappointing its poor documentation considering that this a product cost money.

Few examples:

  • where would be convenient to set the task to be executed? (first task, last one., somewhere in the middle?)
  • Categories and/or tools, which one should be used and under which circunstancies?
  • how to configure parameters as environment variables? the wiki page doesn't explain how to do it properly without breaking things, what the GDN_ (optional) prefix is intended for?
  • how to use it?? e.g. :
    - task: MicrosoftSecurityDevOps@1
      displayName: Microsoft Security DevOps
      env:
        Terrascan_IacDir: '$(build.artifactstagingdirectory)/$(ENV)'

as per the documentation, this config should be correct? because it fails with the following error:

The target directory is not provided. Defaults to the working directory: /home/vsts/work/1/s.
The platform is not provided. Defaults to the current OS: Linux.
Starting tools applicability analysis...
Tools Applicability Infomation:
Found no applicable tools.

Completed tools applicability analysis.
##[error]RunCommandNoOptionsException: No applicable tools were detected. Run requires at least one configuration to run. Provide at least one Guardian config or tool with --config or --tool.
##[error]MSDO CLI exited with an error exit code: 2

oh, wait! if I do this, it works!

    - task: MicrosoftSecurityDevOps@1
      displayName: Microsoft Security DevOps
      env:
        Terrascan_IacDir: '$(build.artifactstagingdirectory)/$(ENV)'
      inputs:
        command: 'run'
        break: true
        categories: 'IaC,secrets,code'
        tools: 'terrascan'

but still not sure if I should use categories, tools or both.

Do you see my concerns?

I hope you can address the documentation gap ASAP.

Many thanks and best regards,

Dominant language
TypeScript
Stars
86
Forks
22
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

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 microsoft/security-devops-azdevops

All issues in microsoft/security-devops-azdevops

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.